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Java Virtual Machine Profiler Interface (JVMPI) 



This document describes the Java Virtual Machine Profiler Interface (JVMPI) in JDK 1 2, It is 
intended for tools vendors to develop profilers that work in conjunction with Sun's Java virtual 
machine implementation. 
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* Notes on JDK1.2 Implementation Limitations 



L Overview 

The JVMPI is a two-way function call interface between the Java virtual machine and an in-process 
profiler agent. On one hand, the virtual machine notifies the profiler agent of various events, 
corresponding to, for example, heap allocation, thread start, etc. On the other hand, the profiler agent 
issues controls and requests for more information through the JVMPI. For example, the profiler agent 
can turn on/off a specific event notification, based on the needs of the profiler front-end. 
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The profiler front-end may or may not run in the same process as the profiler agent. It may reside in a 
different process on the same machine, or on a remote machine connected via the network. The 
JVMPI does not specify a standard wire protocol. Tools vendors may design wire protocols suitable 
for the needs of different profiler front-ends. 

A profiling tool based on JVMPI can obtain a variety of information such as heavy memory 
allocation sites, CPU usage hot-spots, unnecessary object retention, and monitor contention, for a 
comprehensive performance analysis. 

JVMPI supports partial profiling, i.e a user can selectively profile an application for certain subsets of 
the time the virtual machine is up and can also choose to obtain only certain types of profiling 
information. 

In the current version of JVMPI, only one agent per virtual machine can be supported. 

1.1. Start-up 

The user can specify the name of the profiler agent and the options to the profiler agent through a 
command line option to the Java virtual machine. For example, suppose the user specifies: 

java -Xrumnyprofiler:heapdiairip^on f file=log. txt ToBeProf iledClass 

The VM attempts to locate a profiler agent library called myp*° f iler m Java's library directory: 

• On Win32, it is $ JAVAJJOME\bin\myprof iler . dll 

• On SPARC/Solaris, it is $ JAVA_HOME/lib/sparc/libmyprof iler . so 

If the library is not found in the Java library directory, the VM continues to search for the library 
following the normal library search mechanism of the given platform: 

• On Win32, the VM searches the current directory, Windows system directories, and the 
directories in the path environment variable. 

• On Solaris, the VM searches the directories in ld_library_path. 

The VM loads the profiler agent library and looks for the entry point: 

jint JNICALL JVM_OnLoad ( JavaVM *jvm, char *options, void ^reserved) ; 

The VM calls the jVM_OnLoad function, passing a pointer to the JavaVM instance as the first 
argument, and string~ n heapdump=on, f iie=log . txt " as the second argument. The third argument to 
jvM_onLoad is reserved and set to null. 

On success, the jvM_onLoad function must return jni_ok. If for some reason the jVM OnLoad 
function fails, it must return jni_err. 

1.2. Function Call Interface 

The profiler agent can obtain a function call interface by issuing a GetEnv call on the JavaVM pointer. 
For example, the following code retrieves the version of JVMPI interface that is implemented in JDK 
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Get^nv call. 

The jvmpi interface returned by GetEnv has all the functions set up except for Notif yEvent. The 
profiler agent must set up the Notif yEvent function pointer before returning from jvM_onLoad. 

1.3. Event Notification 

The VM sends an event by calling NotifyEvent with a jVMPi_Event data structure as the argument. 
The following events are supported: 

method enter and exit 
object alloc , move , and free 
heap arena create and delete 
GC start and finish 
JNI global reference alloc and free 
JNI weak global reference alloc and free 
compiled method load and unload 
thread start and end 
class file data ready for instrumentation 
class load and unload 

contended Java monitor wait to enter , entered , and exit 
contended raw monitor wait to enter , entered , and exit 
Java monitor wait and waited 
monitor dump 
heap dump 
object dump 

request to dump or reset profiling data 
Java virtual machine initialization and shutdown 

The jVMPi_Event structure contains the event type, the JNiEnv pointer of the current thread, and 
other event-specific information. The event specific information is represented as a union of event- 
specific structures. The JVMPI Events section provides a complete description of all event-specific 
structures. For now, we show the event-specific structures for class load and class unload below. 



typedef struct { 

jint event_type; 
JNIEnv *env__id; 

union { 

struct { 

char *class_name; 
char *source_name; 
jint num_interf aces; 
jint nuiujnethods; 
JVMPI_Method *methods; 
jint num_static_f ields; 
~JVMPI_Field *statics; 
jint num_instance_fields; 
JVMPI_Field ^instances; 
j object ID class_id; 
} class load; 



/* event_type */ 

/* env where this event occurred */ 



/* class name */ 

/* name of source file */ 

/* number of interfaces implemented */ 

/* number of methods in the class */ 

/* methods */ 

/* number of static fields */ 

/* static fields */ 

/* number of instance fields V 

/* instance fields */ 

/* id of the class object */ 



struct { 

j object ID class_id; 
} class unload; 



/* id of the class object */ 
. /* Refer to the section on JVMPI events for a full listing */ 



} u; 
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} JVMPI_E:vent ; 

1.4. JVMPI IDs 

The JVMPI refers to entities in the Java virtual machine as various kinds of IDs. Threads, classes, 
methods, objects, heap arenas and JNI global references all have unique IDs. 

Each ED has a defining event and an undefining event. A defining event provides the information 
related to an ID. For example, the defining event for a thread ED contains, among other entries, the 
name of the thread. 

An ED is valid until its undefining event arrives. An undefining event invalidates the ED, whose value 
may be reused later as a different kind of ID. The value of a thread ED, for example, may be redefined 
as a method ID after the thread ends. 



ID 


data type 


defining event j 


undefining event j 


thread ID 


JNIEnv * 


thread start 


thread end I 


object ID 


jobjectID 


obiect alloc 


obiect free, obiect move, and arena delete! 


class ID 


|j object ID 


class load j 


class unload and obiect move j 


method ID 


jmethodID 


defining class loadl!defining class unload | 


arena ID 


Hint 


arena new ! 


arena delete i 


JNI global ret 1D|| j ob j ect 


global ref alloc 


global ref free j 



Assuming the defining events are enabled during the profiler initialization, the profiler agent is 
guaranteed to be notified of an entity's creation through a defining event, before the entity appears in 
other JVMPI events. 

If the defining events are not enabled, the profiler agent may receive an unknown ED. In that case the 
profiler agent may request the corresponding defining event to be sent on demand by issuing a 
RequestEvent call. 

IDs representing objects have type jobjectID . A class is represented by the object ID of the 
corresponding j ava . lang . Class object. Therefore, class IDs are also of type j ob j ect id. 

A j ob j ectiD is defined by an obiect alloc event, and remains valid in the arena in which the object is 
allocated until one of its undefining events arrive: 

• An obiect free event invalidates an object ID. 

• An obiect move event is a special type of undefining events. Unlike other undefining events 
which signal the end-of-life of the corresponding entities, the object still exists, but its ID 
changes, and it may have been moved to a new arena. 

• An arena delete event invalidates all remaining object IDs in the arena. 

When an object free or arena delete event invalidates an object ID, the object is known as being 
garbage collected. 

Typically, the profiler agent maintains a mapping between j ob j ect ids and its internal representation 
of object identities, and updates the mapping in response to the defining and undefining events for 
JVMPI object IDs. 

Since object IDs may be invalidated during GC, the VM issues all events that contain j ob j ect id 
entries with GC disabled. In addition, the profiling agent must disable GC when it is directly 
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maculating any j object id data types. Otherwise the GC may invalidate a j object id while it is 
being manipulated in the agent code. The profiler agent must make sure that GC is disabled when it 
calls a JVMPI function that either takes a jobjectiD argument or returns a jobjectiD result. If the 
function call is inside an event handler where GC is already disabled, then the profiler agent need not 
explicitly disable the GC again. 

A thread may be identified either by its JNiEnv interface pointer or by the object ID of the 
corresponding j ava . lang . Thread object. The JNiEnv pointer is valid between thread start and 
thread end events, and remains constant during the lifetime of a thread. The j ava . lang . Thread 
object ID, on the other hand, could remain valid after the thread ends, until it is garbage collected. 
The profiler agent can convert a JNiEnv pointer to the corresponding thread object ID by calling the 

GetThreadObject function. 

1.5. Threading and Locking Issues 

The JVMPI is used by the profiler agent that runs in the same process as the Java virtual machine. 
Programmers who write the agent must be careful in dealing with threading and locking issues in 
order to prevent data corruption and deadlocks. 

Events are sent in the same thread where they are generated. For example, a class loading event is 
sent in the same thread in which the class is loaded. Multiple events may arrive concurrently in 
different threads. The agent program must therefore provide the necessary synchronization in order to 
avoid data corruption caused by multiple threads updating the same data structure at the same time. 

In some cases, synchronizing on certain frequent events (such as method entry and method exit) may 
impose unacceptable overhead to program execution. Agents may utilize the thread-local storage 
support provided by the JVMPI to record profiling data without having to contend for global locks, 
and only merge the thread-local data into global profiles at selected intervals. The JVMPI supplies 
the agent with a pointer-size thread-local storage. Following is a simple example that illustrates how 
a profiler agent may take advantage of this feature. Suppose we need to write a profiler agent that 
counts the number of methods executed in each thread. The agent installs event handlers for thread 
start, method entry, and thread end events: 

/* thread start event handler 

* sets up the storage for thread-local method invocation counter 
*/ 

void ThreadStartHandler { JNiEnv *thread_id) 
{ 

int *p_ctr = (int *}malloc {sizeof (int ) ) ; 

CALL (SetThreadLocalStorage) (threaded, p_ctr) ; 

} 

/* method enter event handler 

* increments thread local method invocation counter 
*/ 

void MethodEntryHandler { jmethodID method_id, JNiEnv *thread__id) 

{ 

int *p_ctr = (int *) CALL (GetThreadLocalStorage) (thread_id) ; 
(*p_ctr)++; 

} 

/* thread end handler 

* prints the number of methods executed 
V 

void ThreadEndHandler (JNiEnv *thread_id) 
{ 

int *p_ctr = (int *) CALL (GetThreadLocalStorage) (thread_id) ; 
fprintf (stdout, "Thread %x executed %d methods W, 
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thread_id, (*p_ctr) ) ; 
free (p_ctr ) ; 

} 

The following JVMPI functions can cause event notification to be sent synchronously in the same 
thread during the function execution: 

• RequestEvent 

• CreateSystemThread 

• RunGC 

The RequestEvent function supplies the JVMPI event explicitly requested by the profiler agent. The 
CreateSystemThread function causes thread object allocation and thread start events to be issued. 
The RunGC function causes GC-related events to be generated 

When a profiling agent is loaded into the Java virtual machine, the process can either be in one of 
three modes: multi-threaded mode with GC enabled, multi-threaded mode with GC disabled, and the 
thread suspended mode. Different JVMPI events are issued in different modes. Certain JVMPI 
functions change the process from one mode to another. 

The profiler agent must obey the following guidelines to avoid deadlocks: 

• In the multi-threaded mode with GC enabled, the agent code has a great deal of freedom in 
acquiring locks and calling JVMPI functions. Of course the normal rules of deadlock 
avoidance apply. Different threads must not enter the same set of locks in different orders. 

• When the GC is disabled the agent program must not call any JVMPI function that could 
require new Java objects to be created or cause the garbage collector to run. Currently, such 
functions include CreateSystemThread and RunGC. In addition, programmers need to be 
aware that disabling the GC creates an implicit locking dependency among threads. When the 
GC is disabled, the current thread may not be able to safely acquire certain locks. Deadlocks 
may happen, for example, if one thread disables GC and tries to acquire a lock, while another 
thread already acquired that lock but is triggering a GC. 

• In the thread suspended mode, one or more of the threads have been suspended. In this case, 
the agent program must not perform any operations that may cause the current thread to block. 
Such operations include, for example, the maiioc and f printf functions provided by the 
standard C library. These functions typically acquire internal C library locks that may be held 
by one of the suspended threads. 

1.6 Data Communication between the Profiler Agent and Front-End 

The JVMPI provides a low-level mechanism for a profiler agent to communicate with the virtual 
machine. The goal is to provide maximum flexiblity for the profiler agent to present the data 
depending on the needs of the front-end, and also to keep the processing work done by the virtual 
machine at a minimum. Therefore, the JVMPI does not specify a wire protocol between the profiling 
agent and the front-end. Instead, tools vendors design their own profiling agents that suit the needs of 
their front-ends. 

The following issues need to be considered when designing the wire protocol in order to allow the 
profiler agent and front-end to reside on different machines: 

• Pointer size (e.g., 32 or 64 bit) - all of the JVMPI IDs are of pointer type (see Data Types) . 

• Byte order (little endian or big endian). 

• Bit order (most significant bit first or least significant bit first). 
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i String encoding - the JVMPI uses the UTF-8 encoding as documented in the Java virtual 
machine specification. 

For example, the hprof profiler agent shipped with JDK 1.2 sends the size of all IDs as the first 
record, and uses the standard network byte order for integer and floating-point data. 

2. Interface Functions 

jint (*CreateSystemThread) (char *name, j in t priority, void <*f) (void *) > ; 

Called by the profiler agent to create a daemon thread in the Java virtual machine. 

It is safe for the profiler agent to make this call only after the JVM notifies a 

jvmpi event_init_done and when the system is in a multi-threaded mode with GC enabled. 

Arguments: 

name - name of the thread. 

priority - thread priority; the values can be: 

JVMPI_NORMAL_PRIORITY 

JVMPIJ4AXIMUM_PRIORITY 

JVMPI__MINIMUM_PRIORITY 

f - function to be run by the thread. 

Returns: 

jni_ok - success. 
jni_err - failure. 

jint (*DisableEvent) (jint event_type, void *arg) ; 

Called by the profiler agent to disable the notification of a particular type of event Apart from 
event_type, the profiler agent may also pass an argument that provides additional information 
specific to the given event type. 

All events are disabled when the VM starts up. Once enabled, an event stays enabled until it is 
explicitly disabled. 

This function returns jvmpi_not_available if event _type is jvmpi_event_heap_dump, 

JVMPI_EVENT^MONITOR_DUMP Or JVMPI_EVENT_OBJECT_DUMP. 

Arguments: 

event_type - type of event, JVMPI_EVENT_CLASS_LOAD etc. 

arg - event specific information. 

Returns: 
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jvmpi_success disable succeeded. 

jvmpi_fail disable failed. 

support for disabling the given event type is not 

JVMPI_NOT_AVAILABLE 



void (*DisableGC) (void) ; 

Called by the profiler to disable garbage collection, until EnabledGC is called. DisableGC and 
EnableGC calls may be nested. 

jint (*EnableEvent) (jint event_type , void *arg) ; 

Called by the profiler agent to enable notification of a particular type of event. Apart from 
event type, the profiler may also pass an argument that provides additional information 
specific to the given event type. 

All events are disabled when the VM starts up. Once enabled, an event stays enabled until it is 
explicitly disabled. 

This function returns jvmpi j*ot_available if event_type is jvmpi _event_heap_dump, 
jvmpi_event_monitor_dump or jvmpi_event_object_dump. The profiler agent must use the 
ReouestEvent function to request these events. 

Arguments: 

event_type - type of event, JVMP I_EVENT_CLAS s_load etc. 
arg - event specific argument. 



Returns: 



jvmpi_success enable succeeded. 

jvmp i_fai l enable failed. 

support for enabling the given event type is not 

JVMPI_NOT_AVAILABLE ^PP^ 



void <*EnableGC) (void) ; 

Enables garbage collections. DisableGC and EnableGC calls may be nested. 

void (*GetCalXTracs) { JVMTI_CallTraca *traca, jint depth) ; 

Called by the profiler to obtain the current method call stack trace for a given thread. The 
thread is identified by the env_id field in the jvmpi CallTrace structure. The profiler agent 
should allocate a jvmpi CallTrace structure with enough memory for the requested stack 
depth. The VM fills in the frames buffer and the numjrames field. 

Arguments: 

trace - trace data structure to be filled by the VM. 
depth - depth of the call stack trace. 
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jlong (*GetCurrent.ThxeadCpuTime) (void) ; 

Called by the profiler agent to obtain the accumulated CPU time consumed by the current 
thread. 

Returns: 

time in nanoseconds 

iobjectID (*GetMethodClass) {jmethodID mid) ; 

Called by the profiler agent to obtain the object ID of the class that defines a method. 

The profiler must disable GC before calling this function. 

Arguments: 

mid - a method ID. 
Returns: 

object ID of the defining class, 
void * (*GetThreadI<ocalStorage) (JNIEnv *env_id) ; 

Called by the profiler to get the value of the JVMPI thread-local storage. The JVMPI supplies 
to the agent a pointer-size thread-local storage that can be used to record per-thread profiling 
information. 

Arguments: 

env__id - the JNIEnv * of the thread. 
Returns: 

the value of the thread local storage 

iobiectID <*GotThreadObjdct) < JNIEnv *env) ; 

Called by the profiler agent to obtain the thread object ID that corresponds to a JNIEnv pointer. 

The profiler must disable GC before calling this function. 

Arguments: 

env - JNIEnv pointer of the thread. 
Returns: 
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the thread object ID. 
jint ( * Ge tThr eadS ta tus ) (JNIEnv *env) ; 

Called by the profiler agent to obtain the status of a thread. 

The JVMPI functions suspendThread and ResumeThread have no affect on the status returned 
by GetThreadStatus. The status of a thread suspended through the JVMPI remains unchanged 
and the status at the time of suspension is returned. 

Arguments: 

env - the JNIEnv * of the thread. 
Returns: 

jvmp i_thread_runnable - thread is runnable. 

jvm p I _T hread_mon I tor__wai t - thread is waiting on a monitor. 

jvmpi_thread_condvar_wait - thread is waiting on a condition variable. 

When a thread is suspended (by j ava . lang . Thread . suspend) or interrupted in 
any of the above states the jvmpi_thread_sus-pended or the 

JVMPI_THREAD_INTERRUPTED bit is set. 
void (*NotifyEvent) <JVMPI_ Event *event) ; 

Called by the VM to send an event to the profiling agent. The profiler agent registers the types 
of events it is interested in by calling EnabieEvent, or requests a specific type of event by 

calling RequestEvent . 

When an event is enabled by EnableEvent, the thread that generates the event is the thread in 
which the event is sent. When an event is requested by RequestEvent, the thread that requests 
the event is the thread in which the event is sent. Multiple threads may send multiple events 
concurrently. 

If the event specific information contains a j ob j ect id, this function is called with GC 
disabled. GC is enabled after the function returns. 

The space allocated for the jvMPi Event structure and any event specific information is freed 
by the virtual machine once this function returns. The profiler agent must copy any necessary 
data it needs to retain into its internal buffers. 

Arguments: 

event - the JVMPI event sent from the VM to the profiling agent. 

void (*ProfilerExit) { jint err_ code) ; 

Called by the profiler agent to inform the VM that the profiler wants to exit with error code set 
to err code. This function causes the VM to also exit with the same err_code. 
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Arguments: 

err_code - exit code 
jVMPIRawMonitor (*RawMbnitorCreate) (char *locJc_name) ; 

Called by the profiler to create a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
this function may call arbitrary system functions such as maiioc and block on an internal 
system library lock. 

If the raw monitor is created with a name beginning with an underscore ( • _ 1 ), then its monitor 
contention events are not sent to the profiler agent. 

Arguments: 

lock name - name of raw monitor. 
Returns: 

a raw monitor 

void ( *RawMonitorDestroy) ( JVMP I_RawMoni tor lock_id) ; 

Called by the profiler agent to destroy a raw monitor and free all system resources associated 
with the monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
this function may call arbitrary system functions such as free and block on a internal system 
library lock. 

Arguments: 

lock_id - the raw monitor to be destroyed 

void (*RawMonitorEntar) ( JVMPI_RawMoni tor loc3c — id) ; 
Called by the profiler agent to enter a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
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the current thread may block on the raw monitor already acquired by one of the suspended 
threads. 

Arguments: 

lock id - the raw monitor to be entered 

void <*RawMonitorExit) ( JVMP I_RawMonx to r lock_id) ; 

Called by the profiler agent to exit a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

lock id - the raw monitor to exit 

void (*RawMdnitorNotifYAll) ( JVMPI__RawMoni tor lock_id) ; 

Called by the profiler to notify all the threads that are waiting on a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

lock_id - the raw monitor to notify 

void (*RawMbnitorWaxt) ( JVMP I_RawMoni to r Xoc3t_id, jlong ms) ; 

Called by the profiler agent to wait on a raw monitor for a specified timeout period. Passing 0 
as the timeout period causes the thread to wait forever. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

lock_id - the raw monitor to wait on 
ms - time to wait (in milliseconds). 

jinfc ( *RequestEvent) (jint ©vent_type, void *arg) ; 

Called by the profiler agent to request a particular type of event to be notified* Apart from 
event_type, the profiler agent may also pass an argument that provides additional information 
specific to the given event type. 

This function can be called to request one-time events such as jvmpi_event_heap_dump, 
jvmpi_event j*onitor_dump and jvmpi_EVENT_OBJECT_dump. Notification for these events 
cannot be controlled by the EnableEvent and DisabieEvent functions. 
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In addition, this function can be called to request the defining events for a specific class, 
thread, or object. This is useful when the profiler agent needs to resolve an unknown class, 
method, thread, or object ED received in an event, but the corresponding defining event was 
disabled earlier. 

• The profiler agent may receive information about an unknown class ID by requesting a 
jvmpi event class load event and setting the event-specific argument to the class 
object ID. 

• The profiler agent may receive information about an unknown thread ID by requesting a 
jvmpi event thread start event and setting the event-specific argument to the thread 
object ID. 

• The profiler agent may receive information about an unknown object ID by requesting a 
jvmpi event object allqc event and setting the event-specific argument to the object 
ID. 

Thus the profiler agent can either enable the above three events asynchronously by calling 
EnabieEvent , or request these events synchronously by calling RequestEvent. The requested 
event is sent in the same thread that issued the RequestEvent call, and is sent before the 
RequestEvent function returns. 

The RequestEvent function cannot be used to request other events not listed above. 

Events requested through RequestEvent will arrive with the jvmpi requested event bit set 
in its event_type. 

Arguments: 

event__type - type of event, jvmpi_event__class_load etc. 
arg - event specific argument. 

Returns: 

jvmp i_success request succeeded. 

jvmpi_fail request failed. 

JVMP I_NOT_AVAI LABLE ***** ™*JW » «* 

void ( *ResumeThread) (JNIEnv *env) ; 

Called by the profiler agent to resume a thread. 

Note that a thread suspended by the j a va . lang . Thread . suspend method cannot be resumed 
by the JVMPtResumeThread function. 

Arguments: 

env - the JNIEnv * of the thread. 

void (*RunGC) (void) ; 

Called by the profiler to force a complete garbage collection. This function must not be called 
when GC is disabled. 
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void (*SetThreadl.ocalStorago) (JNIEnv *env_id f void *ptr) ; 

Called by the profiler agent to set the value of the JVMPI thread-local storage. The JVMPI 
supplies to the agent a pointer-size thread-local storage that can be used to record per-thread 
profiling information. 

Arguments: 

env_id - the JNIEnv * of the thread. 

ptr - the value to be entered into the thread-local storage. 

void {* SuspendThread) (JNIEnv *env) ; 

Called by the profiler agent to suspend a thread. The system enters the thread suspended mode 
after this function is called. 

Note that a thread suspended by the JVMPI suspendThread function cannot be resumed by the 
j ava . lang . Thread, resume method. 

In the JDK 1.2 implementation, this function must be called when the GC is disabled. GC must 
remain disabled until all threads have been resumed. 

Arguments: 

env - the JNIEnv * of the thread. 

jboolean ( * ThreadHasRun) (JNIEnv *env) ; 

Called by the profiler to determine if a thread identified by the given JNIEnv pointer has 
consumed CPU time since the last time the thread was suspended by SuspendThread . This 
function must be called when the thread has been resumed by ResumeThread and then 
suspended again by the SuspendThread function. 

Arguments: 

env - the JNIEnv * of the thread. 
Returns: 

jni jtrue - thread got a chance to run. 
jni_false - thread did not get a chance to run. 

3. Events 

JVMPI_EVENT_ARENAJDELETE 

Sent when a heap arena is deleted. 

All objects residing in this arena are freed. An explicit jvmpi event object free is not sent 
for those objects. The profiler agent can infer all the objects currently residing in that arena by 
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keeping track of the object allocations in the arena and all the objects moved in and out of the 
arena. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via malloc). 

This event is always sent between a pair of jvmpi event gc start and 

jvmpx event gc finish events. The profiler agent should acquire all the locks need for 

processing this event in the event handler for jvmpi_event_gc_start. 

struct { 

jint arena_id; 
} delete_arena; 

Contents: 

arena id - ID of the arena being deleted. 

JVMPX_EVENT_ARENA___NEW 

Sent when a new arena for allocating objects is created. 

struct { 

jint arena_id; 

char *arena_name; 
} new__arena; 

Contents: 

arena_id - ID given to the arena, 
arena name - name of the arena. 

JVMP I_EVEKT_CIiAS S_jLO AD 

Sent when a class is loaded in the VM, or when the profiler agent requests a 
jvmpi_event_class_load event by issuing a RequestEvent call. In the latter case, the 
jvmpi_requested_event bit in the event type is set 

This event is issued with GC disabled. GC is re-enabled after Not ifyE vent returns. 

struct { 

char *class_name; 

char *source_name; 

jint num_int erf aces; 

jint num_methods ; 

JVM?I_Method ^methods; 

jint num_static_f ields; 

JVMPI_Field *statics; 

jint num_instance_f ieids; 

JVM?I_Field ^instances; 

iobiectID class_id; 
} ciass_load; 

Contents: 
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classname - name of class being loaded. 

source name - name of source file that defines the class. 

numinterf aces - number of interfaces implemented by this class. 

methods - methods defined in the class. 

numstaticf ields - number of static fields defined in this class. 

statics - static fields defined in the class. 

nuru instance f ields - number of instance fields defined in this class. 

instances - instance fields defined in the class. 

class id - class object ID. 

Note: class IDs are IDs of the class objects and are subject to change when 

JVMPI_EVENT_0BJECTJ40VE arrives. 
JVMP I_E VENT_CLAS S_LOAD_HOOK 

Sent when the VM obtains a class file data, but before it constructs the in-memory 
representation for that class. The profiler agent can instrument the existing class file data sent 
by the VM to include profiling hooks. 

The profiler must allocate the space for the modified class file data buffer using the memory 
allocation function pointer sent in this event, because the VM is responsible for freeing the new 
class file data buffer. 

struct { 

unsigned char *class_data; 

jint class_data_len; 

unsigned char *new_class_data; 

jint new_class_data_ien; 

void * (*ma!loc_f ) (unsigned int) ; 
} class_load_hook; 

Contents: 

class_data - pointer to the current class file data buffer. 

class__data_len - length of current class file data buffer. 
new_class_data - pointer to the instrumented class file data buffer. 
new_class_data_len - length of the new class file data buffer. 
maiioc_f - pointer to a memory allocation function. 

The profiler agent must set new_ciass_data to point to the newly instrumented class file data 
buffer and set new ciass_data_len to the length of that buffer before returning from 

NotifyEvent . It must set both new_class_data and new_class_data_len to die old values if 
it chooses not to instrument this class. 

JVMPI_EVENT_CLASS_UNLOAD 

Sent when a class is unloaded. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 
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struct { 

iobiectID class_ia; 
} class_unload; 

Contents: 

class id - class being unloaded. 

JVMP I_EVENT_COMP ILED_ME THOD_LOAD 

Sent when a method is compiled and loaded into memory. 

struct { 

jmethodID method_id; 

void *code_addr; 

jint code_size; 

jint lineno_table_size; 

JVMPI_Lineno *lineno_table ; 
} compiled_method_load; 

Contents: 

method id - method being compiled and loaded. 

code_addr - address where compiled method code is loaded. 

code_s i ze - size of compiled code, 

lineno tabie size - size of line number table. 

- table mapping offset from beginning of method to the src 

lineno_table ffle ^ number 

JVMP IJEVENT jCGMP I LED_ME THOD__UNLOAD 

Sent when a compiled method is unloaded from memory. 

struct { 

jmethodID method_id; 
} c omp iled__met ho d — unload; 

Contents: 

method_id - compiled method being unloaded. 

JVMPI_EVENT_DATA_DUMP_REQUEST 

Sent by the VM to request the profiler agent to dump its data. This is just a hint and the profiler 
agent need not react to this event. This is useful for processing command line signals from 
users. For example, in JDK 1.2 a CTRL-Break on Win32 and a CTRLA on Solaris causes the 
VM to send this event to the profiler agent. 

There is no event specific information. 

JVMPI EVENT DATA RESET REQUEST 
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Sent by the VM to request the profiler agent to reset its data. This is just a hint and the profiler 
agent need not react to this event. This is useful for processing command line signals from 
users. For example, in JDK 1 .2 a CTRL-Break on Win32 and a CTRLA on Solaris causes the 
VM to send this event to the profiler agent 

There is no event specific information. 

JVMP I_EVENT_GCJFINI SH 

Sent when GC finishes. The profiler agent can release any locks, grabbed during GC start 
notification for handling object free, object move, and arena delete events. The system gets 
back into the multi-threaded mode after this event. 

The event-specific data contains Java heap statistics. 

struct { 

jlong used_objects; 

jlong usedj3bject_space; 

jlong total_object_space; 
} gc_info; 

Contents: 

used_ob j ect s - number of used objects on the heap. 

used ob j ectjpace - amount of space used by the objects (in bytes). 

total object space - total amount of object space (in bytes). 

JVMP I__E VENT_GC__S TART 

Sent when GC is about to start. The system goes into thread suspended mode after this event. 
To avoid deadlocks, the profiler agent should grab any locks that are needed for handling 
object free, object move, and arena delete events in the event handler for this event. 

There is no event specific information. 

JVMPI_EVENT_HEAP_DUMP 

Sent when requested by the RequestEvent function. The profiler agent can specify the level of 
information to be dumped by passing an jVMPi_HeapDumpArq structure to RequestEvent as 
the second argument, with the heap__dump_ievei field set to the desired dump level. 

The dump level values can be one of the following: 

• JVMPI_DUMP_LEVEL_0 

• JVMPI_DUMP_LEVEI,_1 

• JVMPI_DUMP_LEVEL_2 

If a NULL value is passed, then the dump level is set to jvmpi jxjmp _level_2. 
This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 
The event-specific data contains a snapshot of all live objects in the Java heap. 



36 



struct { 

int dump_level; 

char *begin; 

char *end; 

jint num_traces; 

JVMPI_CallTrace *traces; 
} heap__dump; 

Contents: 

dump_level - the dump level specified in ReguestEvent 
begin - beginning of the heap dump 
end - end of the heap dump 

- number of stack traces in which the GC roots reside, 0 for 

aumjraces JVMPI_DUMP_LEVEL_0 

traces - the stack traces in which the GC roots reside 

The format of the heap dump between begin and end depends on the level of information 
requested. The formats are described in detail in the JVMPI Dump Formats section. 

Sent when a JNI global reference is created. The event-specific data contains the JNI global 
reference as well as the corresponding object CD. 

This event is issued with GC disabled. GC is re-enabled after NotifySvent returns. 

struct { 

jobiectID obj_id; 

j object ref_id; 
} jni_globalref_a Hoc; 

Contents: 

obj_id - object ID referred to by the global reference, 
ref _id - JNI global reference. 

JVMPI_EVENT_JNI_GLOBAIiREF_FREE 

Sent when a JNI global reference is deleted. The event-specific data contains the JNI global 
reference that is being deleted. 

struct { 

jobject ref_id; 
} jni_giobalref_free; 

Contents: 

ref _id - JNI global reference. 

JVMPI EVENT JNI WEAK GLOBALREF AIXOC 
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Sent when a JNI weak global reference is created. The event-specific data contains the JNI 
weak global reference as well as the corresponding object ED. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

jobiectID obj_id; 

j object ref_id; 
} jni_globalref_alloc; 

Contents: 

obj_id - object ED referred to by the weak global reference. 
ref_id - JNI weak global reference. 

JVMP I_EVENT_JNI_WEAK_GLOBAIiREF_FREE 

Sent when a JNI weak global reference is deleted. The event-specific data contains the JNI 
weak global reference that is being deleted. 

struct { 

j object ref_id; 
} jni_globalref_free; 

Contents: 

re f _id - JNI weak global reference. 

JVMPI_EVENT_JVM_INIT_DONE 

Sent by the VM when its initialization is done. It is safe to call createSystemThread only 
after this event is notified. 

There is no event specific data. 

JVMPI_EVENT_JVM_SHUTJX>WN 

Sent by the VM when it is shutting down. The profiler typically responds by saving the 
profiling data. 

There is no event specific data. 

JVMP I_E VENT_ME THOD_ENTRY 

Sent when a method is entered. Compared with jvmpi_event_method_entry2, this event does 
not send the j object id of the target object on which the method is invoked. 

struct { 

jmethodID method_id; 
} method; 

Contents: 
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thod ici - the method being entered. 



JVMPI_EVENT_METHOD_ENTRY2 

Sent when a method is entered. If the method is an instance method, the jobjectiD of the 
target object is sent with the event. If the method is a static method, the ob j id field m the 
event is set to null. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

jmethoclID method_id; 

iobiectID obj_id; 
} method_entry2; 

Contents: 

method id - the method being entered. 

obj_id - the target object, null for static methods. 

JVMP I_E VENTJME THOD_EXI T 

Sent when a method is exited. The method exit may be a normal exit, or caused by an 
unhandled exception. 

struct { 

jmethodID method_id; 
} method; 

Contents: 

method_id - the method being entered. 

JVMPI_EVENT_MONITOR__CONTE3SIDED_ENTER 

Sent when a thread is attempting to enter a Java monitor already acquired by another thread. 
This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

jobiectID object; 
} monitor; 

Contents: , 

ob j ect - object ID associated with the monitor 

JVMPI_EVENTJb^NITOR_CONTENDED_ENTERED 

Sent when a thread enters a Java monitor after waiting for it to be released by another thread. 
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This event is issued with GC disabled GC is re-enabled after NotifyEvent returns. 



struct { 

jobiectID object; 
} monitor; 

Contents: 

object - object ID associated with the monitor 

JVMP I_E VENT_MONI TOR__CONTENDED_jEXI T 

Sent when a thread exits a Java monitor, and another thread is waiting to acquire the same 
monitor. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

jobiectID object; 
} monitor; 

Contents: 

ob j ect - object ID associated with the monitor 

JVMP I_E VENT_MONI T OR_DUMP 

Sent when requested by the Requestsvent function. 

The event-specific data contains a snapshot of all the threads and monitors in the VM. 
This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

char *begin; 

char *end; 

jint num_traces ; 

JVMPI_CallTrace *t races ; 

jint *threads_status; 
} moni t o r_durap ; 

Contents: 

begin - start of the monitor dump buffer, 

end - end of the dump buffer 

num__traces - number of thread traces, 
traces - traces of all threads, 

thread status - status of all threads. 

The format of the monitor dump buffer is described in detail in the JVMPI Dump Forma ts 
section. 
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JVMP I_E VENT_MONI TOR_WAl T 

Sent when a thread is about to wait on an object. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

iobiectID object; 

jlong timeout ; 
} monitor_wait ; 

Contents: 

ob j ect - ID of object on which the current thread is going to wait 
(null indicates the thread is in Thread, sleep.) 
^ - the number of milliseconds the thread will wait. (0 indicates waiting 

timeout forever } 
JVMPI_EVENT_^NITORJWAITED 

Sent when a thread finishes waiting on an object 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

iobiectID object; 

jlong timeout; 
} monitor__wait; 

Contents: 

ob j ect - ED of object on which the current thread waited. 

(null indicates the thread is in Thread, sleep.) 
timeout - the number of milliseconds the thread waited. 

JVMPI_EVENT_OBJECT_ALLOC 

Sent when an object is allocated, or when the profiler agent requests a 

jvmpi_event_ob ject_alloc event by issuing a RequestEvent call. In the latter case, the 

jvmpi_requested_event bit in the event type is set. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

jint arena_id; 

iobiectID class_id; 

jint is_array; 

jint size; 

iobiectID obj_id; 
} obj_alloc; 

Contents: 
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arena_id - arena where allocated. 

- class to which this object belongs, or the array element class if 

class_id is _ array is JVMPI_CLASS. 

is array - values can be: 



O V Mir x 


MHRMAT OR.TFPT 


normal object 


JVM PI 




arrav of obiects 


"TT TKAT3 T 




array of booleans 


JVMPI_ 


J3YTE 


array of bytes 


JVMPI_ 


_CHAR 


array of chars 


JVMPI_ 


_SHORT 


array of shorts 


JVMPI_ 


_INT 


array of ints 


JVMPI_ 


_LONG 


array of longs 


JVMPI_ 


_FLOAT 


array of floats 


JVMPI 


DOUBLE 


array of doubles 



size - size in number of bytes, 
ob j id - unique object ID. 

JVMPIJEVENTjOBJECT — DUMP 

Sent when requested by the RequestEvent function. The i object id of the object for which a 
dump is being requested should be passed as the second argument to RequestEvent. 

The profiler agent should request this event with GC disabled. 

The event-specific data contains a snapshot of the object. 

struct { 

jint data_len; 

char *data; 
} object_dump; 

Contents: 

data_ien - length of the object dump buffer 
data - beginning of the object dump 

The format of the object dump buffer is described in detail in the JVMPI Dump Formats 
section. 

JVMP I_EVENT_OB JECT_FREE 

Sent when an object is freed. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via ma Hoc). 

This event is always sent between a pair of jvmpi event gc start and 

jvmpi event gc finish events. The profiler agent should acquire all the locks need for 
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processing this event in the event handler for jvmpi_event_gc_start. 

struct { 

jobiectID obj_id; 
} obj_free; 

Contents: 

obj__id - object being freed. 

JVMPI_EVENTjOBJECT — MOVE 

Sent when an object is moved in the heap. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via maiioc). 

This event is always sent between a pair of jvmpi event gc start and 

jvmpi event gc finish events. The profiler agent should acquire all the locks need for 

processing this event in the event handler for jvmpi_event_gc_start. 

struct { 

jint arena_id; 
iobiectID obj_id; 
j int new_arena_id; 
jobiectID new_obj_id; 
} obj_move; 

Contents: 

arena_id - current arena. 
obj_id . - current object ED. 
new_arena_id - new arena. 
new_obj_id - new object ID. 

JVMP I_EVENT_RAW_MONI TOR_CONTENDED_ENTER 

Sent when a thread is attempting to enter a raw monitor already acquired by another thread. 

struct { 

char *name; 

JVMPI_RawMonitor id; 
} raw_monitor; 

Contents: 

name - name of the raw monitor 
id - ID of the raw monitor 

JVMP I_EVENT_RAW_MONI TOR_CONTENDED_ENTERED 

Sent when a thread enters a raw monitor after waiting for it to be released by another thread. 
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struct { 

char *name; 

.TVMPI_R3wMonitor id; 
} raw monitor; 



Contents: 



name - name of the raw monitor 
id - ID of the raw monitor 

Sent when a thread exits a raw monitor, and another thread is waiting to acquire the same 



monitor. 



struct { 

char *name; 

,TVMPI_R awMonitor id; 
} raw_monitor; 

Contents: 

name - name of the raw monitor 
id - ID of the raw monitor 

JVMPIJ5VENTJIHREAD_END 

Sent when a thread ends in the VM. 

The env id field of the jvMPi.Event received in this event notification is the jniehv interface 
pointer of the thread that ended. 

JVMP I_J2VENT__THREAD_S TART 

Sent when a thread is started in the VM, or when the profiler a §^^ f ±e 
^prEVENT„THREAD_START event by issuing a RequestEvent call. In the latter case, the 
jvmpiIrequestedjcvent bit in the event type is set 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

char *thread_name; 

char *group_name; 

char *parentjname; 

jobiectlD thread_id; 

JNIEnv *thread__env__id; 
} thread_start; 

Contents: 
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thread_name - name of thread being started. 
group_name - group to which the thread belongs, 
pareatname - name of parent. 
thread_id - thread object ID. 
thread_env_id - JNIEnv * of the thread. 

Threads are associated with a JNIEnv pointer and a thread object ID. The JVMPI uses the 
JNIEnv pointer as the thread ID. 

4. Dump Formats 

4.1 Sizes and Types Used in Damp Format Descriptions 

ul : 1 byte 
u2 : 2 bytes 
u4: 4 bytes 
u8 : 8 bytes 
ty: ul where: 



JVMPI_ 


J$ORMAL_OBJ£CT 


normal object 


JVMPI_ 


JZhASS 


array of objects 


JVMPI_ 


^BOOLEAN 


array of booleans 


JVMPI_ 


_BYTE 


array of bytes 


JVMPI_ 


_CHAR 


array of chars 


JVMPI_ 


_SHORT 


array of shorts 


JVMPI_ 


_INT 


array of ints 


JVMPI_ 


_LONG 


array of longs 


JVMPI_ 


_FLOAT 


array of floats 


JVMPI_ 


_DOUBLE 


array of doubles 



vi : values, exact size depends on the type of value: 

boolean, byte 
short, char 
int, float 
long, double 



Ul 

u2 
u4 
u8 



JNIEnv j object ID, and JVMPI_RawMonit or sizeof{void *) 



4.2 Heap Dump Format 

The heap dump format depends on the level of information requested. 

JVMP I_DUMP_LEVEL 0: 

The dump consists of a sequence of records of the following format: 
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ty type of object 

jobjectID Object 

JVMPIJ3UMP_JLEVEL 1: 

The dump format islhe same as that of jvmpi_dump_level_2, except that the following values are 
excluded from the dump: primitive fields in object instance dumps, primitive static fields in class 
dumps, and primitive array elements. 

JVMPI_DUMP_LEVEL 2: 

The dump consists oF a sequence of records, where each record includes an 8-bit record type followed 
by data whose format is specific to each record type. 



Record type 


Record data 


JVMP I_GC_ROOT_UNKNOWN 

(unknown root) 


jobjectID Object I 


JVMP I GC ROOT JNI GLOBAL 

(JNI global ref root) 


jobjectID object ; 
j ob j ect JNI global reference j 


JVMP I GC ROOT JNI LOCAL 

(JNI local ref) 


jobjectID object ! 
JNiEnv * thread 

frame # in stack trace (-1 for : 
u4 empty) 


JVMP I_GC_ROOT_ JAVA__FRAME 

(Java stack frame) 


jobjectID object 
jni En v * thread 

frame # in stack trace (-1 for : 
u4 empty) 


JVMPI_GC_RO0T_NATIVEjSTACK 

(native stack) 


jobjectID Object 

JNiEnv * thread 


JVMP I__GC_ROOT_ST ICKY_CLASS 

(system class) 


jobjectID class object j 

i 


JVMPI_GC_ROOT_THREAD_BLOCK 
frf*fprprif % p frnm thread hlorlc^ 


jobjectID thread object j 
JNI En v * inreaa ; 


JVMPI_GC_ROOT_MONITOR_USED 

(entered monitor) 


jobjectID object I 


JVMP I_GC_CLAS S_DUMP 

(dump of a class object) 


jobjectID Class 
jobjectID super 
jobjectID class loader 
jobjectID signers 
jobjectID protection domain 
void * reserved 
void * reserved 
u4 instance size (in bytes) 
[jobjectID}* interfaces 
u2 size of constant pool 
[ u2 , constant pool index, 
ty, type, 
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vl] * 
[vl] * 


value 

static field values 


JVMPI_GC_INSTANCE DUMP 

(dump of a normal object) 


' jobjectID 
jobjectID 
u4 

C vl] * 


object 
class 

number of bytes that follow 
instance field values (class 
followed by super, super's 
super ...) 


JVMPI_GC_OBJ__ARRAY DUMP 

(dump of an obj ect aiTay) j 


jobjectID 
u4 

jobjectID 
T jobjectID] * 


array object 
number of elements 
element class ID (may be 
null in JDK 1.2) " 
elements 


JVMPI__GC_PRIM_ARRAY_DDMP 

(aump oi a primitive array) 


jobjectID 

u4 

ty 

[vl]* 


array object 
number of elements 
element type 

elements 1 

= ., 1: 



4.3 Object Dump Format 

^?^ P i UffCr i StS °~ Single record which eludes an 8-bit record type, followed bv data 
specific to the record type. The record type can be one of the following: IO "°wea Dy data 

• JVMP I_GC_CLAS S_DUMP 

• JVMPIJ3C_INSTANCE_D0MP 

• JVMPI_GC_OBJ_ARRAY_DUMP 

• JVMPI_GC_PRIM_ARRAY_DUMP 

^£ X X°£S tftf T ^ reC °Ji? type iS S3me 38 described *™ ™ hea P dump format 
section. The > level of information is the same as jvmpi dump level 2, with all of the fiXwin^ 

4.4 Monitor Dump Format 



Record type 


Record data 


JVMPI_MONITOR_JAVAj 

(Java monitor) ; 


jobjectID 
JNIEnv * 
u4 
u4 

[JNIEnv *] + 
u4 

[JNIEnv *] * 


object ID 

owner thread j 
entry count 

number of threads waiting to enter 1 

threads waiting to enter 

number of threads waiting to be 
notified \ 

threads waiting to be notified j 
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char * 


raw moniior name [ 




JVMPI_RawMonitor 


raw monitor ID j 




O LN J. £j i 1 v 


owner thread. 


JVMPI_MONITOR_RAW 

(Raw monitor) 


u4 
u4 

[JNIEnv *] * 


entry count 

number of threads waiting to enter 
threads waiting to enter 




u4 


number of threads waiting to be 
notified j 




[JNIEnv +]* 


threads waiting to be notified j 



5. Data Types 

Characters are encoded using the UTF-8 encoding as documented in the Java virtual machine 
specification. 

jobjectID 

An opaque pointer representing an object ED. 

struct _j object ID; 

typedef struct _jobjectID * jobjectID; 
JVMPI_CallFrame 

A method being executed. 

typedef struct { 

jint lineno; 

jmethodID method_id; 
} JVMPI__CallFrame; 

Fields: 

line number - line number in the source file. 
method_id - method being executed. 

JVMPI__ CallTrace 

A call trace of method execution. 

typedef struct { 

JNIEnv *env_id; 

jint num_frames; 

JVMPI_CallFrame * frames; 
} JVMPI_CallTrace; 

Fields: 
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env id - ED of thread which executed this trace, 
num frames - number of frames in the trace. 

-the jvmpi CaiiFrame s that make up this trace. Callee followed by 

frames 



JVMPI_Field 

A field defined in a class. 



typedef struct { 

char * f ieldjiame ; 

char *f ield_signature; 
} JVMPI_Field; 

Fields: 

field name -name of field 

f ield_signature - signature of field 

JVMPI_ HeapDumpArg 

Additional info for requesting heap dumps. 

typedef struct { 

jint heap_dump_level; 
} JVMPI_HeapDumpArg; 

Fields: 

heap_dump__levei - level of heap dump information, values can be: 

JVMPI_DUMP_LEVELJ3 
JVMPI_DUMP_LEVEL_1 
JVMPI_DUMP_LEVEL_2 

JVMP I_Lineno 

A mapping between source line number and offset from the beginning of a compiled method. 

typedef struct { 

jint offset; 

jint lineno; 
} JVMPI_Lineno; 

Fields: 



offset - offset from beginning of method 
lineno - lineno from beginning of source file 



JVMPI Method 
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A method defined in a class. 

typedef struct { 

char *method_name; 

char * met hod_si gnat ure; 

jint start_lineno; 

j int end_l ineno ; 

jmethodID method_id; 
} JVMPI_Method; 

Fields: 

method_name 
method_s ignature 
start_lineno 
end_lineno 
method_id 

JVMPI_RawMonitor 

An opaque pointer representing a raw monitor. 

struct _JVMPI_RawMonitor; 

typedef struct _JVMPI_RawMonitor * JVMPI_RawMonitor ; 

6. Notes on JDK1.2 Implementation Limitations 

• jvmpi_event_object_alloc events for object arrays are issued with unknown element class 
IDs (i.e., the ciass_id field is always null). 

• On Win32 the following events are not yet supported in the presence of the JIT compiler: 

JVMPI_EVENT_METHOD_ENTRY, 
JVMPI_EVENTJMETHOD_ENTRY2, 
JVMPI_EVENT_METHOD_EXIT, 
JVMPI_EVENT_COMPILED_METHOD_LOAD, and 
JVMPI_EVENT_COMPILED_METHOD_UNLOAD, 

• suspendThread must be called with the GC is disabled. GC must remain disabled until all 
threads have been resumed. 

• The thread start event for the main thread (first thread the VM creates) may arrive after some 
other events that refer to its JNiEnv interface pointer. 

• jvmpi jevent_arena_new and jvmpi_event_arena_delete events are never issued. Arena 
IDs in other events are always set to 1 . 



Last modified: Wed Nov 11 14:14:44 PST 1998 



- name of method 

- signature of method 

- start line number in the source file 

- end line number in the source file 

- ID given to this method 
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A M ETHOD F OR ENABLING COMPREHENSIVE PROFILING OF GARBAGE- 
"""" ^OLLECTEDNIEMORY SYSTEMS 



FIELD OF THE INVENTION 

The present invention relates to computer software, and more specifically to 
enabling comprehensive profiling of garbage-collected memory systems. 



BACKGROUND OF THE INVENTION 
5 Despite the rapid growth in memory sizes of computers, storage in which data is 

placed in a computer requires careful conservation and recycling. Some programming 
languages support static allocation of storage space while others support dynamic 
allocation. Static allocation connotes that storage space is determined at compilation of 
the computer program. In the case of dynamic allocation, storage space is determined 

10 during execution of the programs, known as "run-time". The area of dynamic memory 
reserved for storage space that is determined at run-time is a referred to as a "heap". 

Many programming languages place the responsibility with the programmer to 
explicitly allocate storage and explicitly dispose or free that storage when it is no longer 
needed. Thus, when the programmer has the responsibility of the allocating and recycling 

15 or reclaiming of storage in dynamic memory, the memory management is said to be 
manually performed or "explicit". 

An individually allocated piece of memory in the heap may be referred to herein as 
an "object". The goal is to dispose of unused or dead objects by freeing such objects and 
returning the space associated with such objects to the "free list" or "free pool". The "free 

20 list" or "free pool" is the set of unallocated usable spaces in the heap. However, with 
explicit allocation and deallocation, some objects cannot be deallocated or used because 
they have become "unreachable". The space occupied by an unreachable object is said to 
have "leaked" away. In addition, explicit deallocation may result in "dangling references". 
To illustrate, consider the following. 

25 Data that is dynamically allocated in memory is usually accessible by the user 

program through the roots of the computation of the user program, or by following chains 
of pointers ("references") from these roots. The roots of the computation of a user 
program are those locations that hold values that a user program can manipulate directly. 
Processor registers and the program stack are examples of roots of the computation. Thus, 
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an object in the heap is said to be "live" if its address is held in a root, or there is a 
reference to it held in another live object in the heap. Otherwise, the object is said to be 
"dead". An object becomes unreachable when the last reference to the object is destroyed 
before the object is deallocated. The object is no longer live if there are no references to it. 
5 In addition, such an object cannot be freed (deallocated) because it is unreachable, as there 
are no references leading to it. Objects that are neither live nor free cannot be used or 
recycled by explicit allocation and deallocation, and are called "garbage". Thus, 
unreachable dead objects are "garbage". 

"Dangling references" occur when an object in the heap is deallocated while there 

10 are still references to the object. Dangling references can produce incorrect results. For 
example, if the memory location of the object that was deallocated while there were still 
references to it is reallocated to another of the user program's data structures, then the 
same memory location would represent two different objects. 

Automatic dynamic memory management can obviate the problem of unreachable 

15 objects and dangling references. In one approach, automatic dynamic memory 

management involves assigning the responsibility for dynamic memory management to 
the program's run-time system. The programmer must still request dynamically allocated 
storage to be reserved but the programmer no longer needs to recycle the storage because 
the recycling is done automatically through a process called garbage collection. Garbage 

20 collection can recover unreachable objects by returning the space associated with such 
objects to the free list or free pool. In addition, garbage collection avoids dangling 
references by not deallocating any object while there remains references to it from other 
live objects. 

Furthermore, garbage collection may be useful in correcting the problem of 
25 "fragmentation". Fragmentation occurs in the course of allocating objects of different 

sizes in the heap. There are various strategies for choosing the optimum space in the heap 
to allocate to an object. However, such strategies usually result in areas or "fragments" of 
free pool in the heap. Sometimes the fragments are too small to be useful and are not 
contiguous and therefore, cannot be combined. For example, FIG. 1 illustrates a heap 100. 
30 The shaded areas 102, 104, 106, 108, 110 indicate storage space already in use in heap 
100. The non-shaded areas, 101, 103, 105 indicate fragments of free pool in heap 100. 
Assume that none of the fragments of free pool are large enough to meet the current 
request for allocation of an object. Even though the free pool is not empty, an object 
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cannot be allocated in the heap if none of the fragments are large enough. Thus, garbage 
collection can be employed to reclaim storage space not just when the "free-pool" is empty 
but also to automatically perform compaction of the heap storage space that is in use. 

Garbage collection is one of many features associated with profiling a given user 
5 program such as an application program. "Profiling" describes the monitoring and tracing 
of events that occur during run-time. For example, a profiling tool may provide 
information on how much or how frequently dynamic memory is allocated by each portion 
of the executing application program. As will be explained in greater detail, some of the 
dynamic memory allocation information can be extracted from the object allocation 

10 process and the garbage collection process. 

In one approach, profiling tools are specifically customized and instrumented for a 
specific platform. Typically, tool vendors specialize in providing tools that are only 
suitable for certain platforms. For example, different virtual machine vendors provide 
myriad Java™ virtual machine implementations. Java™ is an object-oriented language, 

1 5 the source code files of which are compiled into a format called bytecode. Bytecode can 
be executed on any machine on which Java run-time system software is installed. The 
Java™ run-time system is known as a Java™ virtual machine, a self-contained operating 
environment that behaves as if it is a separate computer. The Java™ virtual machine 
translates the bytecode's set of instructions into the underlying computer processor's set of 

20 instructions. Thus, a Java™ application will execute in any Java™ virtual machine 
regardless of the hardware and software underlying the system. It would be highly 
desirable if users were given the choice of using any profiling tool that is available in the 
market without worrying if the tool is compatible with the user's particular 
implementation of Java™ virtual machine. 

25 Based on the foregoing, it is desirable to develop a mechanism that supports a wide 

variety of profiling tools for garbage collected memory systems. 

SUMMARY OF THE INVENTION 

A method and system are provided for allowing a profiler to communicate with a 
30 virtual machine without regard to the specific implementation of the virtual machine. A 
wide variety of profilers can be accommodated by using a set of virtual machine profiler 
interface events that are designed to be independent of any method for dynamically 
managing storage allocation and deallocation in a heap within the virtual machine process. 
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The profiler may request specific information with respect to storage allocation and or 
deallocation in the heap. In response, the virtual machine can send the requested 
information using the virtual machine profiler interface events. 

In other aspects, the invention encompasses a computer apparatus, a computer- 
5 readable medium, and a carrier wave configured to carry out the foregoing techniques. 

Many other aspects and features will become apparent from the following 
description. 

BRIEF DESCRIPTION OF THE DRAWINGS 
10 The present invention is illustrated by way of example, and not by way of 

limitation, in the figures of the accompanying drawings and in which like reference 
numerals refer to similar elements and in which: 

FIG. 1 is a block diagram illustrating fragmentation of a heap; 
FIG. 2 is a block diagram illustrating a profiling architecture according to one 
1 5 embodiment of the invention; and 

FIG. 3 is a block diagram that illustrates a computer system 300 upon which an 
embodiment of the invention may be implemented. 

DETAILED DESCRIPTION OF THE PREFERRED EMBODIMENT 
20 Techniques for enabling comprehensive profiling of Java™ virtual machines are 

described. In the following description, for the purposes of explanation, numerous specific 
details are set forth in order to provide a thorough understanding of the present invention. 
It will be apparent, however, to one skilled in the art that the present invention may be 
practiced without these specific details. In other instances, well-known structures and 
25 devices are shown in block diagram form in order to avoid unnecessarily obscuring the 
present invention. 

Although certain embodiments have been described using the Java™ programming 
language, the present invention can be practiced on a variety of programming languages, 
and as such should not seen as limited to only the Java™ programming language. 

30 FUNCTIONAL OVERVIEW 

One embodiment of the invention is a general-purpose profiling interface between 
a virtual machine and the front-end of a profiler. The profiling interface is general enough 
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to support a wide variety of profilers and virtual machine implementations, A general- 
purpose profiling interface offers at least two advantages over direct profiling support in 
the virtual machine implementation. 

First, various profilers are not restricted to one format in presenting profiling 
5 information nor are they restricted in the types of profiling information they can present. 
For example, one profiler may simply record events that occur in the virtual machine trace 
file. Alternatively, another profiler may display information in response to interactive user 
input. 

Another advantage of a general-purpose profiling interface is that a given profiler 
10 can be used with different virtual machine implementations, which support the same 

general-purpose profiling interface. This allows for profiling tool vendors and virtual 

machine vendors to leverage each other's products effectively. 

FIG. 2 is a block diagram illustrating the overall profiler architecture according to 

one embodiment of the invention. The virtual machine profiler interface ("VMPI") 215 is 
1 5 interposed between the virtual machine 210 and the profiler agent 220. Typically, VMPI 

215 ? virtual machine 210 and profiler agent 220 reside in a virtual machine process 200. 

Profiler agent 220 is responsible for communication between the VMPI 215 and a profiler 

front-end 260, which typically resides in a process that is separate from virtual machine 

process 200. In one embodiment of the invention, profiler front-end 260 resides in a 
20 profiler process 250, which is separate from virtual machine process 200 to ensure that the 

resources consumed by profiler front-end 260 are not attributed to the profiled user 

application. Specifications for an exemplary virtual machine profiler interface, "VMPI", 

for a Java™ virtual machine is attached hereto as Appendix A. 

Profiler agent 220 can be programmed to delegate resource-intensive tasks to 
25 profiler front-end 260. Thus, even though profiler agent 220 runs on virtual machine 

process 200, profiler agent 220 does not overly distort the profiling information on the 

user application. 

VMPI 215 is a two-way function call interface between virtual machine 210 and 
profiler agent 220. Typically, profiler agent 220 is implemented as a dynamically loaded 
30 library. Virtual machine 210 makes VMPI function calls to inform profiler agent 220 
about various events that occur during the execution of the user application program as 
indicated by an arrow 216 of FIG. 2, Profiler agent 220 responds by calling back into 
virtual machine 210, as indicated by an arrow 217 of FIG. 2, for the purpose of 
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accomplishing one or more tasks. For example, based on the needs of profiler front-end 
260, profiler agent 220 may disable or enable certain types of events ("VMPI events") as 
they are sent through VMPI 215. The following is an example of how virtual machine 210 
and profiler agent 220 may use VMPI function calls in one embodiment of the invention. 

5 

Profiler agent 220 may register the types of events in which it is interested by 
calling VMPI function: 

jint (*EnableEvent)(jint eventjype, void *arg) 

Alternatively, Profiler agent 220 may call the following VMPI function to request 
10 a particular type of event: 

jint (*RequestEvent)(jint eventjype, void *arg) 

In response, virtual machine 210 may send an event that was requested by profiler 

agent 220 by calling the following VMPI function: 

void (*NotifyEvent) (JVMPI_Event * event) 
15 VMPI function calls are explained in greater detail in Appendix A. 

In one embodiment of the invention, VMPI events may be data structures 
consisting of an integer indicating the VMPI event type, an identifier of the thread in 
which the VMPI event occurred, followed by information that is specific to the VMPI 
event. Examples of some VMPI events are: 

20 

VMPI_Eventj3C_Start 
VMPI_Event__GC__Finish 

As an illustration, virtual machine 210 sends the VMPI_Event_GC_Start event 
25 before the start of garbage collection ,and when garbage collection is completed, virtual 
machine 210 sends the VMPI_Event_GC_Finish event. These and other VMPI events are 
explained in greater detail in Appendix A. 

ALLOCATION AND GARBAGE COLLECTION EVENTS 
In one embodiment of the invention, VMPI 215 is a flexible and yet 
30 comprehensive interface that uniformly accommodates a wide variety of memory 

allocation and garbage collection methods. Implicit in garbage collection methods are 
methods for memory allocation. Appendix A contains a detailed description of 
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representative VMPI events. However, the focus is on the following set of profiling 
interface events that support all known types of garbage collection methods. Such 
profiling events are herein referred to as garbage collection algorithm-independent events 
since they support all known types of garbage collection methods and are further described 
5 in greater detail in Appendix A. These garbage collection algorithm-independent events 
may be used by virtual machine 210 to convey profiling information to profiler agent 220. 

The abstract concept of a "heap arena" is used for describing allocation of new 
objects within the heap. A heap arena describes a logically partitioned portion of the heap. 
In one embodiment of the invention, all object allocations occur in a given heap arena 
10 even when there are a plurality of arenas. After the objects are allocated, they may be 
moved from one heap arena to another as explained below. To help explain the set of 
events, each event is described by its components. The first component is the event-type. 
The second component is the event-specific information contained in a pair of parentheses 
following the event-type. 

1 5 new_arena (arena ID) 

deletearena (arena ID) 
new object (arena ID, object ID, class ID) 
delete_pbject (arena ID) 

move_pbject (old arena ID, old object ID, new arena ID, new object ID) 

20 For example, "new_arena" is the event type and "arena ED" is the corresponding 

event-specific information. The virtual machine interface refers to entities in the virtual 
machine by various types of IDs. Threads, classes, methods, objects, heap arenas all have 
unique IDs. The subject of IDs is further detailed in Appendix A. In brief, each ID has a 
defining event and an undefining event. A defining event provides information related to 

25 the ID. For example, the defining event for an "object ID" contains, among other entries, 
the class ID of the object. The defining event for an object ID is "object allocate". The 
object ID remains valid until one of its undefining events arrive. The undefining events 
for an object ID are as follows: 

30 The "object free" event, which invalidates an object ID. 
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The "object move" event, which signifies that the object still exists but its ID is 

changed, and or that it may have been moved to another heap arena. 

The "arena delete" event, which invalidates all remaining object IDs in the heap 

arena. 

5 

When an object ID is invalidated either by an "object free" event or an "arena 
delete" event, the object is said to be "garbage collected". 

Virtual machine 210 sends a "new arena" event to profiler agent 220 via VMPI 215 
when a new heap arena for allocating objects is created. In one embodiment of the 
10 invention, the "new__arena" event may be described as follows in a Java™ virtual machine 
implementation. 

Struct { 

jint arena_id; 
1 5 char *arena_name; 

} new arena; 

The "arena_id" is the ID assigned to the new heap arena, and "arena name" is the 
name of the new heap arena. 

Similarly, virtual machine 210 sends a "delete_arena" event to profiler agent 220 
20 through VMPI 215 when freeing all the objects remaining in the particular heap arena. 

Thus, profiler agent 220 is apprised of which objects remain in the heap arena by keeping 
track of the object allocations in the heap arena as well as the movement of objects in and 
out of the heap arena. In one embodiment of the invention, the "delete_arena" event may 
be described as follows in a Java™ virtual machine implementation. Note that the 
25 arena_id is the ID of the heap arena being deleted. 

Struct { 

jint arena id; 
} delete arena; 

30 

Virtual machine 210 sends to profiler agent 220 a "newobject" event, also known 
as an "object_allocate" event when an object is allocated, or when profiler agent 220 
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requests such an event. In one embodiment of the invention, the "object_allocate" event 
may be described as follows in a Java™ virtual machine implementation. 



Struct { 
5 jint arena_id; 

jobjectID classed; 
jint is__array; 
jint size; 
jobjectID obj_id; 
10 } obj_alloc; 



"ArenajLd" identifies the heap arena where the objects are to be allocated. 

"Classed" either identifies the class to which the object that are to be allocated belong, or 

the array element class is the "is_array" has a value of "JVMPI_Class". The "is_array" 
1 5 can have values that indicate that it is a normal object, an array of objects, an array of 

Boolean expressions, etc. Further details may be found in Appendix A. "Size" is the 

number of bytes, and "obj_id" is the unique object ID. 

Virtual machine 210 sends to profiler agent 220 a "deleteobject" event, also 

known as an "object_free" event when an object is freed. In one embodiment of the 
20 invention, the "object_free" event may be described as follows in a Java™ virtual machine 

implementation. 



Struct { 

jobjectID obj_id; 
25 } obj free; 



"Objid" identifies the object being freed. 

30 Virtual machine 210 sends to profiler agent 220 a "move object" event, also 

known as an "object_move" event when an object is moved to a new location in the heap. 
In one embodiment of the invention, the "objectjmove" event may be described as follows 
in a Java™ virtual machine implementation. 
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Struct { 

jint arena id; 
jobjectID obj_id; 
5 jint new__arena_id; 

jobjectID new_obj_id; 
} obj_move; 

"Arena_id" identifies the current heap arena where the object resides. "Obj_id" 
identifies the current object ID of the object to be moved. "New_arena_Jd" identifies the 
1 0 new heap arena to which the object is to be moved, "New_obj_id" is the new ID assigned 
to the object after it is moved. 

The use of allocation and garbage collection events are described below in 
connection with various garbage collection methods, such as the Mark-and-Sweep garbage 
collector, the Mark-Compact garbage collector, the Two-Space Copying garbage collector, 
15 the Generational garbage collector, and the Reference-Counting garbage collector. 

PROFILING INFORMATION 

The "new_arena" and "delete_arena" events, as in the case of Generational garbage 
collection, provide useful profiling information such as the number of generations of 
objects, which objects are most likely to die young, and the relative age of the objects. 

20 The "new_objecf * and "delete_object" events provide profiling information such as 

when, which and how many objects are allocated and deleted, as well as information on 
the classes to which the objects belong. 

The "move_object M event, as in the case of the Mark-Compact garbage collection, 
would provide profiling information such as how frequently compaction had to be 

25 performed and what are the associated costs. The frequent need for compaction may be a 
reflection of the unsuitability of the allocation scheme for the particular user program 
application. In the case of Generational garbage collection, the "move_object" provides 
information as to survivability of objects. The longer surviving objects are moved to older 
heap arenas (older generations). 

30 The combination of all five events provide information on the number of live 

objects that the program is using at any given time. Such information is highly useful in 
profiling garbage-collected memory systems. 
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MARK-AND-SWEEP GARBAGE COLLECTOR 

The invention may be used with a Mark-and-Sweep garbage collector. The Mark- 
and-Sweep collector is an automatic storage and reclamation tracing garbage collection 
technique. Whether an object is alive may be determined directly or indirectly. The 
5 indirect methods are also referred to as "tracing" methods. Direct methods require for 
each object in the heap that a record be maintained of all references to that object from 
other heap objects or roots. In contrast, indirect or tracing garbage collectors visit all 
reachable objects, starting from the roots of the computation and by following pointers. 
Thus, the objects that were not visited by the garbage collector are made available for 
10 recycling. 

Under the Mark-and-Sweep method, objects are not reclaimed immediately after 
they become garbage, but remain unreachable and undetected until all available storage in 
the heap is exhausted. If a request is then made for storage space, useful processing is 
temporarily suspended while the garbage collector is called to sweep all currently unused 

1 5 objects from the heap back into the free-pool. The Mark-and-Sweep collector, being a 
tracing collector, relies on a global traversal of all live objects to determine which objects 
are available for reclamation. The traversal of the live objects is the "marking" phase and 
the reclamation of unused objects is the "sweep" phase. During the "marking" phase, a bit 
associated with each cell, known as the "mark-bit" is reserved for use by the mark-and- 

20 sweep collector. The collector uses the "mark-bit" to record if the object is reachable from 
the roots of the computation. The mark-bit is set as each reachable object is visited. 
During the "sweep" phase, the unmarked objects are returned to the free-pool. 

When used in conjunction with the allocation and garbage collection events 
described above, the Mark-and-Sweep collector would issue a "new_object" event when 

25 allocating objects. Only one heap arena is needed. The collector sends a "delete_object" 
event when returning dead objects to the free-pool. 

MARK-SWEEP-COMPACT GARBAGE COLLECTOR 
The invention may be used with a Mark-Compact garbage collector. Under the 
Mark-Compact scheme, in addition to marking live objects in the heap, objects are 
30 relocated within the heap and the values of pointers that referred to the relocated objects 
are updated. The marked (live) objects are relocated in order to compact the heap. At the 
end of the compaction phase, the heap will be divided into two contiguous areas. One area 
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will hold the active or live objects while the other area will hold the free-pool. There are 
several schemes related to the placement of the relocated objects in the heap. For 
example, under the "arbitrary" scheme, the live objects may be relocated without regard 
for their original order, or whether they point to one another. However, such a scheme 
5 often leads to reduced virtual memory performance. Under the "linearizing" scheme, live 
objects that originally pointed to one another are moved into adjacent positions. Under the 
"sliding" scheme, live objects are slid to one end of the heap. 

When used in conjunction with the allocation and garbage collection events 
described above, the Mark-Compact collector would issue a "new_object" event when 

10 allocating objects and a "delete_pbject" event when returning dead objects to the free- 
pool. In addition, the collector would issue a "moveobject" event in order to perform 
compaction of the heap. Only one heap arena is used in this case because the old and new 
heap arena IDs in the "move_object" event are the same. In this case, the relocation of the 
live objects can be viewed as simply reshuffling the positions of the live objects within the 

15 same area. Thus, there is no need for the abstraction of separate multiple heap arenas. 

TWO-SPACE-COPYING GARBAGE COLLECTOR 

The invention may be used with a Two-Space-Copying garbage collector. The 
Two-Space-Copying collector is tracing collector. Under the Two-Space-Copying 
scheme, the collector first divides the heap equally into two semi-spaces before any 

20 allocation of objects is performed. Allocation of objects occurs only in one of the semi 
spaces, referred to herein as the "Fromspace". The other semi space, referred to herein as 
the "Tospace", is reserved for later use. When garbage collection begins, the collector 
traverses the live objects in the "Fromspace" and copies each live object to the "Tospace". 
After all the live objects in the "Fromspace" have been traced, a replica of the live objects 

25 has been created in the "Tospace", and the user application program is restarted. The 

garbage objects are abandoned in the "Fromspace". The collector is said to "scavenge" the 
live objects from amidst the garbage. 

When used in conjunction with the allocation and garbage collection events 
described above, the Two-Space-Copying collector would issue two "new_arena" events 

30 to create two heap arenas representing the two semi-spaces. The collector would issue a " 
new object" when allocating objects. During garbage collection, the collector would issue 
"moveobject" events as it scavenges the live objects for placement into the reserved heap 
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arena. Once all the live objects have been scavenged from the old heap arena, the collector 
sends a "deletearena" event to delete the old heap arena and thereby freeing all the 
objects in the old heap arena. Next, in order to restore the two-space scheme, the collector 
would issue a "new__arena" event using the same arena_id as the old heap arena that was 
5 deleted. 

* 

GENERATIONAL GARBAGE COLLECTOR 

The invention may be used with a Generational garbage collector. Under the 
Generational garbage collection scheme, objects are segregated by age into two or more 
regions of the heap called generations. Different generations can then be garbage collected 

10 at different frequencies, with the youngest generation being collected more frequently than 
the older generations. Objects are first allocated in the youngest generation, but are 
promoted into older generations if they survive long enough. 

When used in conjunction with the allocation and garbage collection events 
described above, the Generational collector would issue a "newarena" event to create an 

1 5 heap arena for each generation of objects. In addition, the Generational collector would 
issue a "newobject" to allocate objects in the youngest generation. The collector would 
issue a "move_object" event as live objects are scavenged from a younger generation to an 
older generation. All objects (garbage) in an heap arena are implicitly freed when the 
collector sends a "delete_arena" event to delete the youngest generation at any given time. 

20 Next, in order to restore the generational scheme, the collector would issue a 

"newarena" event using the same arena-id as the youngest generation that was deleted. 

REFERENCE-COUNTING GARBAGE COLLECTOR 
The Reference-Counting garbage collector is a direct method of storage 
reclamation. Under the Reference-Counting scheme, each object has a reference count 
25 field used for counting the number of references to the object from other live objects or 
roots. Free objects have a reference count of zero. When anew object is allocated from 
the free-pool, its reference count is set to one. Each time a pointer is set to refer to an 
object, the value of the object's counter is increased by one. Likewise, when a reference to 
an object is deleted, the object's counter is decreased by one. When an object's counter 
30 drops to zero, there are no more pointers to the object and the object becomes garbage. 



14 

When used in conjunction with the allocation and garbage collection events 
described above, the Reference-Counting collector sends a "newobject" event each time 
an object is allocated, and it sends a "delete_object" event when the reference count of an 
object drops to zero. 

5 IMPLEMENTATION MECHANISMS 

A. OVERVIEW 

The approach described herein for comprehensive profiling of Java™ virtual 
machines may be implemented in computer software, in hardware circuitry, or as a 
combination of computer software and hardware circuitry. Accordingly, the invention is 
1 0 not limited to a particular computer software or hardware circuitry implementation. 

The present invention is both flexible and powerful enough to meet the needs of a 
wide variety of virtual machine implementations and profiling tools. The invention's 
power lies in its provision for capturing the behavior of memory systems of the virtual 
machine using a set of events that are independent of any underlying garbage collection 
1 5 algorithm that has been implemented in the virtual machine. 

Although certain embodiments have been described using the Java™ programming 
language, the present invention can be practiced on a variety of programming languages, 
and as such should not seen as limited to only the Java™ programming language. 

B. IMPLEMENTATION HARDWARE 

20 FIG. 3 is a block diagram that illustrates a computer system 300 upon which an 

embodiment of the invention may be implemented. Computer system 300 includes a bus 
302 or other communication mechanism for communicating information, and a processor 
304 coupled with bus 302 for processing information. Computer system 300 also includes a 
main memory 306, such as a random access memory (RAM) or other dynamic storage 

25 device, coupled to bus 302 for storing information and instructions to be executed by 

processor 304. Main memory 306 also may be used for storing temporary variables or other 
intermediate information during execution of instructions to be executed by processor 304. 
Computer system 300 further includes a read only memory (ROM) 308 or other static 
storage device coupled to bus 302 for storing static information and instructions for 
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processor 304. A storage device 310, such as a magnetic disk or optical disk, is provided 
and coupled to bus 302 for storing information and instructions. 

Computer system 300 may be coupled via bus 302 to a display 312, such as a 
cathode ray tube (CRT), for displaying information to a computer user. An input device 
5 314, including alphanumeric and other keys, is coupled to bus 302 for communicating 

information and command selections to processor 304. Another type of user input device is 
cursor control 316, such as a mouse, a trackball, or cursor direction keys for communicating 
direction information and command selections to processor 304 and for controlling cursor 
movement on display 312. This input device typically has two degrees of freedom in two 

10 axes, a first axis (e.g., x) and a second axis (e.g., y), that allows the device to specify 
positions in a plane. 

The invention is related to the use of computer system 300 for implementing 
comprehensive profiling of Java™ virtual machines. According to one embodiment of the 
invention, implementing comprehensive profiling of Java™ virtual machines is provided 

15 by computer system 300 in response to processor 304 executing one or more sequences of 
one or more instructions contained in main memory 306, Such instructions may be read 
into main memory 306 from another computer-readable medium, such as storage device 
3 10. Execution of the sequences of instructions contained in main memory 306 causes 
processor 304 to perform the process steps described herein. One or more processors in a 

20 multi-processing arrangement may also be employed to execute the sequences of 

instructions contained in main memory 306. In alternative embodiments, hard-wired 
circuitry may be used in place of or in combination with software instructions to 
implement the invention. Thus, embodiments of the invention are not limited to any 
specific combination of hardware circuitry and software. 

25 The term "computer-readable medium" as used herein refers to any medium that 

participates in providing instructions to processor 304 for execution. Such a medium may 
take many forms, including but not limited to, non-volatile media, volatile media, and 
transmission media. Non-volatile media includes, for example, optical or magnetic disks, 
such as storage device 310. Volatile media includes dynamic memory, such as main 

30 memory 306. Transmission media includes coaxial cables, copper wire and fiber optics, 
including the wires that comprise bus 302. Transmission media can also take the form of 
acoustic or light waves, such as those generated during radio wave and infrared data 
communications. 
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Common forms of computer-readable media include, for example, a floppy disk, a 
flexible disk, hard disk, magnetic tape, or any other magnetic medium, a CD-ROM, any 
other optical medium, punch cards, paper tape, any other physical medium with patterns of 
holes, a RAM, a PROM, and EPROM, a FLASH-EPROM, any other memory chip or 
5 cartridge, a carrier wave as described hereinafter, or any other medium from which a 
computer can read. 

Various forms of computer readable media may be involved in carrying one or more 
sequences of one or more instructions to processor 304 for execution. For example, the 
instructions may initially be carried on a magnetic disk of a remote computer. The remote 

10 computer can load the instructions into its dynamic memory and send the instructions over a 
telephone line using a modem. A modem local to computer system 300 can receive the data 
on the telephone line and use an infrared transmitter to convert the data to an infrared signal. 
An infrared detector coupled to bus 302 can receive the data carried in the infrared signal 
and place the data on bus 302. Bus 302 carries the data to main memory 306, from which 

1 5 processor 304 retrieves and executes the instructions. The instructions received by main 

memory 306 may optionally be stored on storage device 310 either before or after execution 
by processor 304. 

Computer system 300 also includes a communication interface 318 coupled to bus 
302. Communication interface 318 provides a two-way data communication coupling to a 

20 network link 320 that is connected to a local network 322, For example, communication 
interface 318 may be an integrated services digital network (ISDN) card or a modem to 
provide a data communication connection to a corresponding type of telephone line. As 
another example, communication interface 318 may be a local area network (LAN) card to 
provide a data communication connection to a compatible LAN. Wireless links may also 

25 be implemented. In any such implementation, communication interface 318 sends and 
receives electrical, electromagnetic or optical signals that carry digital data streams 
representing various types of information. 

Network link 320 typically provides data communication through one or more 
networks to other data devices. For example, network link 320 may provide a connection 

30 through local network 322 to a host computer 324 or to data equipment operated by an 
Internet Service Provider (ISP) 326. ISP 326 in turn provides data communication 
services through the world wide packet data communication network now commonly 
referred to as the "Internet" 328. Local network 322 and Internet 328 both use electrical, 
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electromagnetic or optical signals that carry digital data streams. The signals through the 
various networks and the signals on network link 320 and through communication 
interface 318, which carry the digital data to and from computer system 300, are 
exemplary forms of carrier waves transporting the information. 
5 Computer system 300 can send messages and receive data, including program 

code, through the network(s), network link 320 and communication interface 318. In the 
Internet example, a server 330 might transmit a requested code for an application program 
through Internet 328, ISP 326, local network 322 and communication interface 318. In 
accordance with the invention, one such downloaded application provides for 
10 implementing comprehensive profiling of Java™ virtual machines as described herein. 

The received code may be executed by processor 304 as it is received, 
and/or stored in storage device 310, or other non-volatile storage for later execution. In 
this manner, computer system 300 may obtain application code in the form of a carrier 
wave. 

15 In the foregoing specification, the invention has been described with reference to 

specific embodiments thereof. It will, however, be evident that various modifications and 
changes may be made thereto without departing from the broader spirit and scope of the 
invention. The specification and drawings are, accordingly, to be regarded in an 
illustrative rather than a restrictive sense. 
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APPENDIX A 



Java Virtual Machine Profiler Interface (JVMPI) 



This document describes the Java Virtual Machine Profiler Interface (JVMPI) in JDK 1 .2. It is 
intended for tools vendors to develop profilers that work in conjunction with Sun's Java virtual 
machine implementation. 
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• 
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1. Overview 



The JVMPI is a two-way function call interface between the Java virtual machine and an in-proccss 
profiler agent On one hand, the virtual machine notifies the profiler agent of various events, 
corresponding to, for example, heap allocation, thread start, etc. On the other hand, the profiler agent 
issues controls and requests for more information through the JVMPI For example, the profiler agent 
can turn on/off a specific event notification, based on the needs of the profiler firont-cnd. 
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is 

The profiler front-end may or may not run in the same process as the profiler agent. It may reside in a 
different process on the same machine, or on a remote machine connected via the network. The 
JVMPI does not specify a standard wire protocol. Tools vendors may design wire protocols suitable 
for the needs of different profiler front-ends. 

A profiling tool based on JVMPI can obtain a variety of information such as heavy memory 
allocation sites, CPU usage hot-spots, unnecessary object retention, and monitor contention, for a 
comprehensive performance analysis, 

JVMPI supports partial profiling, Le a user can selectively profile an application for certain subsets of 
the time the virtual machine is up and can also choose to obtain only certain types of profiling 
information. 

In the current version of JVMPI, only one agent per virtual machine can be supported. 
1.1. Start-up 

The user can specify the name of the profiler agent and the options to the profiler agent through a 
command line option to the Java virtual machine. For example, suppose the user specifies: 

java -xrumayprofilex:neapdump*on # file=log.txt ToBeProf iledClass 

The VM attempts to locate a profiler agent library called aypro£iZer in Java's library directory: 

• On Win32, it is S JAVA^HOMEXbinWyprof iler .dll 

• On SPARC/Solaris, it 7s $ JAVA_HOME/lib/sparc/iibmyprofiler . so 

If the library is not found in the Java library directory, the VM continues to search for the library 
following the normal library search mechanism of the given platform: 

• On Win32, the VM searches the current directory, Windows system directories, and the 
directories in the path environment variable. 

• On Solaris, the VM searches the directories in ld_library_patk. 

The VM loads the profiler agent library and looks for the entry point: 

jint JNICALL JVM^OnLo ad (JavaVM *jvm, char ^options, void ^reserved) ; 

The VM calls the jvM_onLoad function, passing a pointer to the javaVM instance as the first 
argument, and string ~heapdump«on r f ile~iog.txt w as the second argument. The third argument to 
JVM_onLoad is reserved and set to null, 

On success, the jvM_onLoad function must return jni_ok. If for some reason the jVM_onLoad 
function fails, it must return JNI_ERR. 

1.2. Function Call Interface 

The profiler agent can obtain a function call interface by issuing a Ge tEnv call on the JavaVM pointer. 
For example, the following code retrieves the version of JVMPI interface (hat is implemented in JDK 
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1.2: 

JVMPI_Interface * j vmpi_interf ace ; 

JNIEXPORT jint JNICALL JVMJDnLoad ( JavaVM *jvm, char ^options, void Reserved) 

{ int res - (* j vm) ->GetEnv { j vm, (void *^ & jvxupi_interf ace, JVMPI_VERSI0N_1 ) 
if (res < 0) { 

return JNI_ERR; 

/* use entries in j vmpi__interf ace +/ 

} 

The jvmpx interface structure defines the function call interface between the profiler agent and the 
VM: 

/* interface functions */ 
typedef struct { 

jint version; /* JVMPI version */ 

/* interface implemented by the profiler */ 

void ( * NotifvEvent ) (JVMPI Event * event ) ; 

/* interface implemented by the JVM */ 

jint (*EnableEvent) (jint event_type, void *arg) ; 
jint f » DisableEv€nt ) (jint event_type, void *arg) ; 
j^nt (* ReauestEvent ) (lint event_type, void *arg) ; 

void f » GetCallTrace ) ( JVMPI^CallTrace *trace, jint depth) ; 

void f * Profiler£xit ) (jint) ; 

JVMPI_RawMonitor (» RawMonitorCreate ) (char **lock_name) ; 

void T* RawMonitorEnter ) { JVMPI^RawMonitor lock_id) ; 

void ( + RawMonitorExit ) {JVMPI RawMonitor iock__id) ; 

void (* RawMonitorWait i (JVMPI RawMonitor lock_ id, jlong as); 

void (* RawMonitorNotif vAll ) ( JVMPI^RawMonitor lock_id) ; 

void (* RawMonitorDestrov ) (JVMPI RawMonitor lock__id) ; 



jlong ( * GetCurrentThreadCpuTime ) (void) ; 
void ( + SuspendThread ) (JNIEnv *env) ; 
void I * Re^umeThread ) (JNIEnv + env) ; 
jint ( * GetThreadStatus ) (JNIEnv *env) ; 
j boolean ( * ThreadHasRun ) (JNIEnv *env) ; 

jint (* CreateSvsteihThread ) (char *name, jint priority, void (*f ) (void *)) 
void ( + SetThreadI,ocalStoraae ) (JNIEnv *env_id, void *ptr) ; 
void * ( * GetThreadLocalStorace ) (JNIEnv *env_JLd) ; 

void (» DisableGC ) (void) ; 
void (*£nableGC) (void) ; 
void (* RunGC ) (void) ; 

jobjectID (^ GetThreadObnect ) (JNIEnv *env) ; 
jobjectID (* GetMethodClass ) HmethodID mid),- 
} JVMPI Interface; 



The GetEnv function returns a pointer to a JVMPi_mterf ace whose version field indicates a 
JVMPI version that is compatible to the version number argument passed in the GetEnv call. Note 
that the value of the version field is not necessarily identical to the version argument passed in the 
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GetEnv call. 

The jvwpi^interf ace returned by GetEnv has all the functions set up except for NotifyEvent. The 
profiler agent must set up the NotifyEvent function pointer before returning from Jvw_onLoad. 

1-3. Event Notification 



The VM sends an event by calling NotifyEvent with a JVMPi_Event data structure as the argument. 
The following events arc supported: 



• method enter and exit 

• object alloc % move, and free 

• heap arena create and delete 

• GC start and finish 

• JNI global reference alloc and free 

• JNI weak global reference alloc and free 

• compiled method load and unload 

• thread start and end 

• class file data ready for instrumentation 

• class load and unload 

• contended Java monitor wait to enter , entered, and exit 
- contended raw monitor wait to enter, entered, and exit 

• Java monitor wait and waited 

• monitor dump 

• heap dump 

• object dump 

• request to dump or reset profiling data 

• Java virtual machine initialization and shutdown 



The JVKFi_Event structure contains the event type, the JNiEnv pointer of the current thread, and 
other event-specific information. The event specific information is represented as a union of event- 
specific structures. The JVMPI Events section provides a complete description of all event-specific 
structures. For now, we show the event-specific structures for class load and class unload below. 



typedef struct { 

j int event_type ; 
JNIEnv *env_id; 

union { 

struct { 

char *class__name; 
char *source_name; 
jint num_ interfaces; 
jint nuitTinethods ; 
JVMPI_Method *methods; 
jint num static fields ; 
JVM£I_Field *statics; 
jint num__instance_f ields; 
JVMPI_Field ^instances; 
j object ID class_id; 
) ciass_ioad; 

struct { 

jobjectID class id; 
} class_unload; 

... /* Refer to the section on 

} u; 



/* cvent_type */ 

/* env where this event occurred */ 



/* class name */ 

/* name of source file */ 

/* number of interfaces implemented */ 

/* number of methods in the class V 

/* methods */ 

/* number of static fields */ 

/* static fields */ 

/* number of instance fields */ 

/* instance fields */ 

/* id of the class object */ 



/* id of the class object */ 



JVMPI events for a full listing */ 
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} JVMPI_Event; 

1.4. JVMPI IDs 

The JVMPI refers to entities in the Java virtual machine as various kinds of IDs. Threads, classes, 
methods, objects, heap arenas and JNI global references all have unique IDs. 

Each ID has a defining event and an undefining event. A defining event provides the information 
related to an ID. For example, the defining event for a thread ID contains, among other entries, the 
name of the thread. 

An ID is valid until its undefining event arrives. An undefining event invalidates the ED, whose value 
may be reused later as a different kind of 3D. The value of a thread ID, for example, may be redefined 
as a method ID after the thread ends. 



u> 1 


datatype {defining event jjandefining event 


thread ID | 


jKlEnv * jjthread start Jthreadend 


object ID | 
class ID | 


job j ectio jobiect alloc Uobiect tree, object move, and arena delete) 
j obj ect iDflclass load flclass ™l oad 211(1 obiect move 


method ID \ 


jmethodlD]jdefttung class load]|defining class unload 


arena ID ] 


j int jjarena new |]arexxa delete 


JNI global ret ID 


j obj ect ijslobal ret alloc ||plobai ref free 



Assuming the defining events are enabled during the profiler initialization, the profiler agent is 
guaranteed to be notified of an entity's creation through a defining event, before the entity appears in 
other JVMPI events. 

If the defining events are not enabled, the profiler agent may receive an unknown ID. In that case the 
profiler agent may request the corresponding defining event to be sent on demand by issuing a 
RequestEvent call. 

IDs representing objects have type jobjectiD . A class is represented by the object ID of the 
corresponding java.iang. class object Therefore, class IDs are also of type j object ID. 

A j obj ect ID is defined by an obiect alloc event, and remains valid in the arena in which the object is 
allocated until one of its undefining events arrive: 

• Ail obiect free event invalidates an object ID. 

• An obiect move event is a special type of undefining events. Unlike other undefining events 
which signal the cnd-of-life of the corresponding entities, the object still exists, but its ID 
changes, and it may have been moved to a new arena. 

• An arena delete event invalidates all remaining object IDs in the arena. 

When an object free or arena delete event invalidates an object ID, the object is known as being 
garbage collected. 

Typically, the profiler agent maintains a mapping between j object ids and its internal representation 
of object identities, and updates the mapping in response to the defining and undefining events for 
JVMPI object IDs. 

Since object IDs may be invalidated during GC, the VM issues all events that contain jobjectiD 
entries with GC disabled. In addition, the profiling agent must disable GC when it is directly 
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manipulating any j object ID data types. Otherwise the GC may invalidate a jobpectiD while it is 
being manipulated in the agent code. The profiler agent must make sure that GC is disabled when it 
calls a JVMPI function that either takes a jobjectm argument or returns a jobjectiD result If the 
function call is inside an event handler where GC is already disabled, then the profiler agent need not 
explicitly disable the GC again- 

A thread may be identified either by its JNiEnv interface pointer or by the object ID of the 
corresponding j ava . lang . Thread object. The JNIEnv pointer is valid between thread start and 
thread end events, and remains constant during the lifetime of a thread. The j ava . lang . Thread 
object ID, on the other hand, could remain valid after the thread ends, until it is garbage collected. 
The profiler agent can convert a jNiEnv pointer to the corresponding thread object ID by calling the 
GetThreadQbi ect function, 

1.5. Threading and Locking Issues 

The JVMPI is used by the profiler agent that runs in the same process as the Java virtual machine. 
Programmers who write the agent must be careful in dealing with threading and locking issues in 
order to prevent data corruption and deadlocks. 

Events are sent in the same thread where they are generated. For example, a class loading event is 
sent in the same thread in which the class is loaded. Multiple events may arrive concurrently in 
different threads. The agent program must therefore provide the necessary synchronization in order to 
avoid data corruption caused by multiple threads updating the same data structure at the same time. 

In some cases, synchronizing on certain frequent events (such as method entry and method exit) may 
impose unacceptable overhead to program execution. Agents may utilize the thread-local storage 
support provided by the JVMPI to record profiling data without having to contend for global locks, 
and only merge the thread-local data into global profiles at selected intervals. The JVMPI supplies 
the agent with a pointer-size thread-local storage. Following is a simple example that illustrates how 
a profiler agent may take advantage of this feature. Suppose we need to write a profiler agent that 
counts the number of methods executed in each thread. The agent installs event handlers for thread 
start, method entiy, and thread end events: 

/* thread start event handier 

* sets up the storage for thread-local method invocation counter 
*/ 

void ThreadStartHandler (JNIEnv *thread id} 
{ 

int *p_ctr - (int *)malloc (sizeof (int) ) ; 
CALL (SetThreadLocalStorage) (thread id, p ctr) ; 
} ~ 

/* method enter event handler 

* increments thread local method invocation counter 
*/ 

void MethodEntryHandler (jmethodlD method id, JNIEnv ^thread id) 
I 

int *p_ctr = (int *) CALL (Get ThreadLocalStorage) (threaded) ; 
(*p_ctr}++; 

) 

/* thread end handler 

* prints the number of methods executed 
*/ 

void ThreadEndHandler ( JKlEnv +thread id) 
{ 

int *p_ctr - (int *) CALL (Get ThreadLocalStorage) (thread id); 
fprintf (stdout, "Thread %x executed %d methods \n* # " 
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threaded, (*p_ctr) ) : 
free (p_ctr ) ; 

) 

The following JVMPI functions can cause event notification to be sent synchronously in the same 
thread during the function execution; 

• ReouestEvent 

• CreateSvstemThread 

• RunGC 

The RecuestEvent function supplies the JVMPI event explicitly requested by the profiler agent. The 
CreateSystemThread function causes thread object allocation and thread start events to be issued. 
The RunGC function causes GC-related events to be generated. 

When a profiling agent is loaded into the Java virtual machine, the process can either be in one of 
three modes: multi-threaded mode with GC enabled, multi-threaded mode with GC disabled, and the 
thread suspended mode. Different JVMPI events are issued in different modes. Certain JVMPI 
functions change the process from one mode to another. 

The profiler agent must obey the following guidelines to avoid deadlocks: 

• In the multi-threaded mode with GC enabled, the agent code has a great deal of freedom in 
acquiring locks and calling JVMPI functions. Of course the normal rules of deadlock 
avoidance apply. Different threads must not enter the same set of locks in different orders. 

• When the GC is disabled the agent program must not call any JVMPI function that could 
require new Java objects to be created or cause the garbage collector to run, Currently, such 
functions include createSystemThread and RunGC. In addition, programmers need to be 
aware that disabling the GC creates an implicit locking dependency among threads. When the 
GC is disabled, the current thread may not be able to safely acquire certain locks. Deadlocks 
may happen, for example, if one thread disables GC and tries to acquire a lock, while another 
thread already acquired that lock but is triggering a GC. 

• In the thread suspended mode, one or more of the threads have been suspended. In this case, 
the agent program must not perform any operations that may cause the current thread to block. 
Such operations include, for example, the malioc and f print f functions provided by the 
standard C library. These functions typically acquire internal C library locks that may be held 
by one of the suspended threads. 

1.6 Data Communication between the Profiler Agent and Front-End 

The JVMPI provides <a low-level mechanism for a profiler agent to communicate with the virtual 
machine. The goal is to provide maximum flexiblity for the profiler agent to present the data 
depending on the needs of the front-end, and also to keep the processing work done by the virtual 
machine at a minimum. Therefore, the JVMPI does not specify a wire protocol between the profiling 
agent and the front-end. Instead, tools vendors design their own profiling agents that suit the needs of 
their front-ends. 

The following issues need to be considered when designing the wire protocol in order to allow the 
profiler agent and front-end to reside on different machines: 

• Pointer size (e.g., 32 or 64 bit) - all of the JVMPI IDs are of pointer type (see Data TypesV 

• Byte order (little endian or big endian). 

• Bit order (most significant bit first or least significant bit first). 
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• String encoding - the JVMPI uses the UTF-8 encoding as documented in the Java virtual 
machine specification. 

For example, the hprof profiler agent shipped with JDK 1.2 sends the size of all IDs as the first 
record, and uses the standard network byte order for integer and floating-point data. 

2. Interface Functions 

jint (*CreatcSystamTKaread) (char ♦name, jint priority, void (*f) (void *)); 
Called by the profiler agent to create a.dacmon thread in the Java virtual machine. 

It is safe for the profiler agent to make this call only after the JVM notifies a 

jvmpi event_init_done and when the system is in a multi-threaded mode with GC enabled. 

Arguments: 

name - name of the thread. 

priority - thread priority; the values can be: 

JVMPI_NORMAL_PRIORITY 
JVMP I_MAXIMUM_PRI ORI T Y 
JVMPI_J4INIMUM_PRIORITY 

f - function to be run by the thread. 

Returns: 

jni_ ok - success. 
JttI__ERR - failure. 

Jint <*DisableEvent} (jint: event._type , void *arg> ; 

Called by the profiler agent to disable the notification of a particular type of event. Apart from 
event type, the profiler agent may also pass an argument that provides additional information 
specific to the given event type. 

All events are disabled when the VM starts up. Once enabled, an event stays enabled until it is 
explicitly disabled. 

This function returns jvmpi_not_available if evcnt_type is jvmpi_event_heap_dump, 

JVMPI_EVEOT_MONITOR__DUMP or*JVMPI_£VENT_OBJECT_DUMP- 
Arguments: 

event_type - type of event, jvmpi_&vent_ciass_load etc. 
arg - event specific information. 



Returns: 



27 



jvmpi_success disable succeeded. 

jvmpi_fail disable failed. 

^ support for disabling the given event type is not 

void (*DisableGC) (void) ; 

Called by the profiler to disable garbage collection until EnabiedGC is called. DisableGC and 
EnableGC calls may be nested. 

jint (*EnableEvent) (jint event_type , void *arg) ; 

Called by the profiler agent to enable notification of a particular type of event. Apart from 
event jtype, the profiler may also pass an argument that provides additional information 
specific to the given event type. 

All events are disabled when the VM starts up. Once enabled, an event stays enabled until it is 
explicitly disabled. 

This function returns JVMPI_NOT__AVAIL*ABLE if event_type is JVMPI_EVBNT_H£AP_DUMP, 

jvmpi_event_MONITOR_dump or JvmpI_Event_OB ject_DUMP. The profiler agent must use the 
RequestEvent function to request these events. 

Arguments: 

event_type - type of event, JVMPI_EVENT_CLASSJL,OAD etC- 

arg - event specific argument. 

Returns: 

jvwfi_success enable succeeded. 

jvmpi_fail enable failed. 

T7 , ftTP support for enabling the given event type is not 

void <*EnableGC) (void) ; 

Enables garbage collections. DisableGC and EnableGC calls maybe nested. 

void <*GetCallTrace) ( JVMPI_CallTrace *trace, jint depth) ; 

Called by the profiler to obtain the current method call stack trace for a given thread. The 
thread is identified by the emr_id field in the jvmpi CallTrace structure. The profiler agent 
should allocate a jvmpi CallTrace structure with enough memory for the requested stack 
depth. The VM fills in the frames buffer and the num_f rames field. 

Arguments: 

trace * trace data structure to be filled by the VM. 
depth - depth of the call stack trace. 
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jlong (*GetOurrentThxeadCpuTime) (void.) ; 

Called by the profiler agent to obtain the accumulated CPU time consumed by the current 
thread. 

Returns: 

time in nanoseconds 
i obi ect ID (*GetMathodClass> (jmethodID mid) ; 

Called by the profiler agent to obtain the object ID of the class that defines a method. 

The profiler must disable GC before calling this function. 

Arguments: 

mid - a method ED. 
Returns: 

object ID of the defining class. 

void * ( *GetThreadX^calStorage) (JNIEnv *env_id) ; 

Called by the profiler to get the value of the JVMPI thread-local storage. The JVMPI supplies 
to the agent a pointer-size thread-local storage that can be used to record per-thread profiling 
information. 

Arguments: 

env_id - the owiEnv * of the thread. 
Returns: 

the value of the thread local storage 

iob-jgctXP (*OetTlure3.dOb3ect.) (JNIEnv *env) ; 

Called by the profiler agent to obtain the thread object ID that corresponds to a JNXEnv pointer. 

The profiler must disable GC before calling this function. 

Arguments: 

env - jNlEnv pointer of the thread. 
Returns: 
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the thread object ED. 

jint (*G«tThrQadStatue) (JNIEnv +env) ; 

Called by the profiler agent to obtain the status of a thread. 

The JVMPI functions SuspendThread and ResumeThread have no affect on the status returned 
by GetThreadstatus. The status of a thread suspended through the JVMPI remains unchanged 
and the status at the time of suspension is returned. 

Arguments: 

env - the JNIEnv * of the thread. 
Returns: 

JVM p I _T K R£AD_RUNN AB le - thread is runnable. 
jvmpi_thread__monitor_wait - thread is waiting on a monitor. 
jvmpi_THREAD_condvak_wait - thread is waiting on a condition variable. 

When a thread is suspended (by j av a . lang . Thread . suspend) or interrupted in 
any of the above states the jvmpi_thread_suspended or the 
JVMPI„THREAD_INTERRUPTED bitlS set 

void ( *NotifyEvent) ( JVMP I__E vexi t * event) ; 

\ 

Called by the VM to send an event to the profiling agent. The profiler agent registers the types \ 
of events it is interested in by calling EnableE^ent . or requests a specific type of event by I 
calling ReauegtEvent . J 

When an event is enabled by EnableEvent, the thread that generates the event is the thread in 
which the event is sent. When an event is requested by Request Event, the thread that requests 
the event is the thread in which the event is sent Multiple threads may send multiple events 
concurrently. 

If the event specific information contains a j object id, this function is called with GC 
disabled. GC is enabled after the function returns. 

The space allocated for the jVMPl_Event structure and any event specific information is freed 
by the virtual machine once this function returns. The profiler agent must copy any necessary 
data it needs to retain into its internal buffers. 

Arguments: 

event - the JVMPI event sent from the VM to the profiling agent. 

void («JPro£ilerExit) (jint err_ code) ; 

Called by the profiler agent to inform the VM that the profiler wants to exit with error code set 
to err code. This function causes the VM to also exit with the same err_code. 
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Arguments: 

err ccde - exit code 
JVMPI_RawMoni tcr { * RawMoni torCreate ) (char +lock__name) ; 
Called by the profiler to create a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
this fimction may call arbitrary system functions such as malloc and block on an internal 
system library lock. 

If the raw monitor is created with a name beginning with an underscore ( f _ 1 ), then its monitor 
contention events are not sent to the profiler agent 

Arguments: 

lock_name - name of raw monitor- 
Returns: 

a raw monitor 

void <*RavMonitorD©stx-oy) I JVMPI_RavMonitor loek_id) ; 

Called by the profiler agent to destroy a raw monitor and free all system resources associated 
with the monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
this fimction may call arbitrary system functions such as free and block on a internal system 
library lock. 

Arguments: 

lock id - the raw monitor to be destroyed 

void. ( * RawMoni toarEnt^r ) ( JVMP I_RavMoni to x: loc3c__id) ; 

Called by the profiler agent to enter a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

It is not safe for the profiler agent to call this function in the thread suspended mode because 
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the current thread may block on the raw monitor already acquired by one of the suspended 
threads. 

Arguments: 

lock_id - the raw monitor to be entered 

/oid ( ^RawHonJutorExit) < JVMPI RawMoni tor loc3c_id) ; 

Called by the profiler agent to exit a raw monitor. 

Raw monitors are similar to Java monitors, The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

iock_id - the raw monitor to exit 

void (*RavHoni-tor:KotifyAll) ( JVMP I^RavMonitor lock_±d> ; 

Called by the profiler to notify all the threads that are waiting on a raw monitor. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

lock_id - the raw monitor to notify 

void ( *RawMoni toxWai c ) ( JVHPI Jte.wMoni tor loekjld, jlong as) ; 

Called by the profiler agent to wait on a raw monitor for a specified timeout period. Passing 0 
as the timeout period causes the thread to wait forever. 

Raw monitors are similar to Java monitors. The difference is that raw monitors are not 
associated with Java objects. 

Arguments: 

lock_id - the raw monitor to wait on 
ms - time to wait (in milliseconds). 

jinti (*RequestEvent) (jint event^type , void *arg) ; 

Called by the profiler agent to request a particular type of event to be notified. Apart from 
event type, the profiler agent may also pass an argument that provides additional information 
specific to the given event type. 

This function can be called to request one-time events such as jvmpi^event_heap_dump, 
jvmpi event_monitor_dump and Jvmpi_event_object_dump. NotificatiorTfor these events 
cannoF be controlled by the EnableEvent and DisableEvent functions. 
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In addition, this function can be called to request the defining events for a specific class, 
thread or object. This is useful when the profiler agent needs to resolve an unknown class, 
method, thread, or object ED received in an event, but the corresponding defining event was 
disabled earlier. , 

• The profiler agent may receive information about an unknown class ED by requesting a 
jvmPI EVENT class load event and setting the event-specific argument to the class 
object ID. 

• The profiler agent may receive information about an unknown thread ID by requesting a 
jvmpi event thread START event and setting the event-specific argument to the thread 

object ID. " f t . ^ , 

• The profiler agent may receive information about an unknown object ID by requesting a 
jv mpi EVENT OBJECT alloc event and setting the event-specific argument to the object 

5x ~~ " 

Thus the profiler agent can either enable the above three events asynchronously by calling 
EnableEvent , or request these events synchronously by calling Reques t Event . The requested 
event is sent in the same thread that issued the Request Event call, and is sent before the 
Reques tEuent function returns. 

The RequestEvent function cannot be used to request other events not listed above. 

Events requested through RequestEvent will arrive with the jvmpi_requested_event bit set 
in its event_type. 

Arguments ; 

eventjtype - type of event, jvmpi_evxnt j:iass_load etc. 
arg - event specific argument. 

Returns: 

JVMPI SUCCESS request succeeded. 

jvmpi_FAIL request failed 

support for issuing the requested event type is not 
jvmpi_not_available av ^f lable . 

void (*RQSi3meThread> (JNIEnv *env) ; 

Called by the profiler agent to resume a thread. 

Note that a thread suspended by the j ava . lanq . Thread, suspend method cannot be resumed 
by the JVMPI ResuiueThread function. 

Arguments: 

env - the JNIEnv * of the thread. 

void (*RunGC) (void) ; 

Called by the profiler to force a complete garbage collection. This function must not be called 
when GC is disabled 
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void <*SetThr*adi,ocalStorage) (JNIEnv *env_id, void *ptr) ; 

Called by the profiler agent to set the value of the JVMPI thread-local storage. The JVMPI 
supplies to the agent a pointer-size thread-local storage that can be used to record per-thread 
profiling information. 

Arguments: 

env_id - the jni Env * of the thread. 

p tr - the value to be entered into the thread-local storage. 

void <*Suspend2Hread) (JHIEnv *env) ; 

Called by the profiler agent to suspend a thread. The system enters the thread suspended mode 
after this function is called. 

Note that a thread suspended by the JVMPI SuspendThread function cannot be resumed by the 

j ava . lang . Thread . resume method. 

In the JDK 1 .2 implementation, this function must be called when the GC is disabled. GC must 
remain disabled until all threads have been resumed. 

Arguments: 

env - the JNIEnv * of the thread. 

j boolean (*ThreadHasRun) {JNIEnv *env) ; 

Called by the profiler to determine if a thread identified by the given JNIEnv pointer has 
consumed CPU time since the last time the thread was suspended by SuspendThread . This 
function must be called when the thread has been resumed by ResumeThread and then 
suspended again by the SuspendThread function. 

Arguments: 

env - the JNIEnv * of the thread. 

Returns: 

jni TRUE - thread got a chance to run. 

JNI false - thread did not get a chance to run. 

3. Events 

JVMPI_EVENT_AR£NAJDEI£TE 

Sent when a heap arena is deleted. 

All objects residing in this arena are freed. An explicit jvmpi event object free is not sent 
for those objects. The profiler agent can infer all the objects currently residing in that arena by 
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keeping track of the object allocations in the arena and all the objects moved in and out of the 
arena. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via maiioc). 

This event is always sent between a pair of Jvmpi event gc START and 

jvm pi event GC FINISH events. The profiler agent should acquire all the locks need for 

processing this event in the event handler for ovmp i _E VENT_gc__s TART . 

struct { 

jint arena__id; 
} delete_arena; 

Contents: 

arena_id - ID of the arena being deleted. 
jvmpi_£vent_am:ha_new 

Sent when a new arena for allocating objects is created. 

struct { 

jint arena_id; 

char *arena_ name; 
} new_arena; 

Contents; 

arena_id - ED given to the arena. 
arena_name - name of the arena* 

Sent when a class is loaded in the VM, or when the profiler agent requests a 
JVMPI_EVENT_class_load event by issuing a ReouestEvent call. In the latter case, the 
jvmpi_kequested_EVENT bit in the event type is set. 

This event is issued with GC disabled. GC is re-enabled after WotifyEvent returns. 

struct { 

char *class_name; 

char *source__name ; 

jint num_interfaces; 

jint nuia_rnethods; 

JVM? I Method *methods; 

jint nuiu static_f ields; 

JVH?I_Field *statics; 

jint num_instance_f ields; 

JVMPIField * instances; 

nobiectID class_id; 
} class load; 



Contents: 
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class_name - name of class being loaded. 

source_name - name of source file that defines the class. 

num_interf aces - number of interfaces implemented by this class, 

methods - methods defined in the class. 

num_3tatic_fields - number of static fields defined in this class, 

statics - static fields defined in the class. 
nuui_ins tance_f ields - number of instance fields defined in this class, 

instances - instance fields defined in the class. 

class_id - class object ID, 

Note: class IDs are IDs of the class objects and are subject to change when 
jvmpi_event_object_move arrives. 

JVKP I_E VE NT_CIAS S_10AD_HOOK • 

Sent when the VM obtains a class file data, but before it constructs the xn-memory 
representation for that class. The profiler agent can instrument the existing class file data sent 
by the VM to include profiling hooks. 

The profiler must allocate the space for the modified class file data buffer using the memory 
allocation function pointer sent in this event, because the VM is responsible for freeing the new 
class file data buffer. 

struct { 

unsigned char *class_data; 

jint cla5s_data_len; 

unsigned char *new_class_data; 

3 int new_clas s_dat a_len ; 

void * (*malloc_f) (unsigned int); 
} class_load_hook; 

Contents: 

class_data - pointer to the current class file data buffer. 

ciass_data_len - length of current class file data buffer. 
new_class_data - pointer to the instrumented class file data buffer. 
new_class_data_len - length of the new class file data buffer. 
maiioc_f - pointer to a memory allocation function. 

The profiler agent must set new_ciass_data to point to the newly instrumented class file data 
buffer and set new_ciass_data_len to the length of that buffer before returning from 
NotifyEvent . It must set both new__cXass_data and new^class^data^len to the old values if 
it chooses not to instrument this class. ~ 

JVMPIJBVEOTjCIASSJOKLOAD 

Sent when a class is unloaded. 

This event is issued with GC disabled. GC is re-enabled after Not ifvE vent returns. 
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struct { 

jobiectID class_id; 
) class_unload; 

Contents: 

ciass_id - class being unloaded. 

JVHPI_EVENT_CC^IIXDJMETH0D_lOAD 

Sent when a method is compiled and loaded into memory. 

struct { 

jiaethodlD method_id; 

void *code_addr; 

jint code^size; 

jint lineno_table_ size; 

JVMPI_LxnenC> *lineno_table; 
} compiled__method_load; 

Contents: 

- method being compiled and loaded. 

- address where compiled method code is loaded. 

- size of compiled code, 
size - size of line number table. 

- table mapping offset from beginning of method to the sre 
file line number. 

JVMPI_EVEKT_COMPIljED_METRODJUNIiOAD 

Sent when a compiled method is unloaded from memory. 

struct { 

jmethodID iuethod_id; 
) compiled_method_ unload; 

Contents: 

method_id - compiled method being unloaded. 

JVMPI^EVENT_DATA_DUMP_REQOEST 

Sent by the VM to request the profiler agent to dump its data. This is just a hint and the profiler 
agent need not react to this event This is useful for processing command line signals from 
users. For example, in JDK 1.2 a CTRL-Break on Win32 and a CTRL A on Solaris causes the 
VM to send this event to the profiler agent. 

There is no event specific information. 

JVMPI EVENT DATA RESET REQUEST 



method_id 
*code_addr 
code^size 
lineno__table 

lineno table 
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Sent by the VM to request the profiler agent to reset its data. This is just a hin t and the profiler 
agent need not react to this event. This is useful for processing command line signals from 
users. For example, in JDK 1 .2 a CTRL-Break on Win32 and a CTRLA on Solaris causes the 
VM to send this event to the profiler agent. 

There is no event specific information. 

OVMPI_EVENT_GC__FINISH 

Sent when GC finishes. The profiler agent can release any locks, grabbed during GC start 
notification for handling object free, object move, and arena delete events. The system gets 
back into the multi-threaded mode after this event. 

The event-specific data contains Java heap statistics. 

struct { 

jlong used_objects; 

jlong used__object_space; 

jlong total_object_space; 
} gc_info; 

Contents: 

used_ob j ects - number of used objects on the heap. 

used_ obj ect_space - amount of space used by the objects (in bytes). 

total_object_space - total amount of object space (in bytes). 

JVMP I_EVENT_GC_START 

Sent when GC is about to start. The system goes into thread suspended mode after this event. 
To avoid deadlocks, the profiler agent should grab any locks that are needed for handling 
object free, object move, and arena delete events in the event handler for this event 

There is no event specific information. 

JVMFI_EVENT_HEAP_DOMP 

Sent when requested by the RequestEvent function. The profiler agent can specify the level of 
information to be dumped by passing an Jvmpi HeapDumpAra structure to RequestEvent as 
the second argument, with the heap_dump_ievel field set to the desired dump level. 

The dump level values can be one of the following: 
- JVMP I_DUMP_LEVEL_0 

• JVMPI__DUMP_LEVEL_1 

• JVMPI_D0MP_LEVEL_2 

If a NULL value is passed, then the dump level is set to jvmfi_domp level_2. 
This event is issued with GC disabled. GC is re-enabled after NotifvEvent returns. 
The event-specific data contains a snapshot of all live objects in the Java heap. 
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struct { 

i n t dump_l evel; 

char *begin; 

char *end; 

jint num_traces; 

JVM PI CallTrace *traces; 
} heap_dump; 

Contents: 



dump_level - the dump level specified in Re guest Event 
begin - beginning of the heap dump 
end - end of the heap dump 

- number of stack traces in which the GC roots reside, 0 for 

numtraces JVMPI J5UMPJLEVELJ) 

traces - the stack traces in which the GC roots reside 

The format of the heap dump between begin and end depends on the level of information 
requested. The formats are described in detail in the JVMPI Dump Formats section. 

JVMPI_EVENT_JKI_GLOBAIxREF_AIiIiOC 

Sent when a JNI global reference is created. The event-specific data contains the JNI global 
reference as well as the corresponding object ID. 

This event is issued with GC disabled. GC is re-enabled after Not if vEvent returns. 

struct { 

iobiectlD. obj_id; 

j object xef_id; 
) jni__globalref_alloc; 

Contents: 

ob j_xd - object ID referred to by the global reference. 
ref_id - JNI global reference. 



OVMPI_EVENT_JNI_GIOBAIiREF_FREE 

Sent when a JNI global reference is deleted. The event-specific data contains the JNI global 
reference that is being deleted- 

struct { 

j object ref^id; 
} jni_globalref__£ree; 

Contents: 

ref _id - JNI global reference. 



JVMPI EVENT JNI WEAK GLOBALKEF ALLOC 
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Sent when a JNI weak global reference is created. The event-specific data contains the JNI 
weak global reference as well as the corresponding object ID, 

This event is issued with GC disabled. GC is re-enabled after Not if ve vent returns. 

struct { 

i object IP obj__id; 

j object ref_id; 
} jni_globalref_alloc; 

Contents: 

ob j_id - object ID referred to by the weak global reference, 
ref_id - JNI weak global reference. 

JVMPI EVENT_^JNX_WEAK_GLOBAI A REF_FREE 

Sent when a JNI weak global reference is deleted. The event-specific data contains the JNI 
weak global reference that is being deleted. 

struct { 

j object ref_id; 
} jni_globalref_f ree; 

Contents: 

ref_id - JNI weak global reference. 

Sent by the VM when its initialization is done. It is safe to call CreateSystemThread only 
after this event is notified. 

There is no event specific data. 

JVMP I JSVENT_JVW_SKOX__pOWlT 

Sent by the VM when it is shutting down. The profiler typically responds by saving the 
profiling data. 

There is no event specific data. 

JVMP I_JEVENT_ME THOD_ENTRY 

Sent when a method is entered. Compared with jvmpi_event_METHODjentry2, this event does 
not send the jobjectiD of the target object on which the metfibd is invoked. 

struct { 

jmethodID method_id; 
} method; 

Contents: 
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n\ethod_id - the method being entered. 

iTVMPI_£VENT_METHOD_ENTRY2 

Sent when a method is entered. If the method is an instance method, the iobiectlP of the 
target object is sent with the event. If the method is a static method, the obj__id field in the 
event is set to NULL, 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

jmethodID method__id; 

iobiectXD obj_xd; 
} method_entry2; 

Contents: 

method_id - the method being entered. 

ob j_id - the target object, null for static methods. 

JVMP I__E VENT_ME THOD_EXI T 

Sent when a method is exited. The method exit may be a normal exit, or caused by an 
unhandled exception. 

struct { 

jitiethodID method_id; 
) method; 

Contents: 

method_id - the method being entered. 

JVMP I E VElNT^MDNITOR^CX3NTENDED__ENTER 

Sent when a thread is attempting to enter a Java monitor already acquired by another thread. 

This event is issued with GC disabled. GC is re-enabled after Not! fvE vent returns. 

struct '{ 

iobiectlP object; 
> monitor; 

Contents: 

ob j ect - object ID associated with the monitor 

JVMPI_EVEOT_MOKITOR_CX3OTEHDED_EOTEHED 

Sent when a thread enters a Java monitor after waiting for it to be released by another thread. 
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This event is issued with GC disabled. GC is re-enabled after NotifvEvent returns - 

struct { 

-ioMectlP object; 
} monitor; 

Contents: 

ob j ect - object ID associated with the monitor 

JVMPI_EVENT_MQNI T0R_COOTENDED_EXXT 

Sent when a thread exits a Java monitor, and another thread is waiting to acquire the same 
monitor. 

This event is issued with GC disabled, GC is re-enabled after NotifvEvent returns. 

struct { 

jobiectID object; 
} monitor; 

Contents: 

ob j ect - object ID associated with the monitor 

JVMPIJEVENTJMONITOR^DXMP 

Sent when requested by the RequestEvent function. 

The event-specific data contains a snapshot of all the threads and monitors in the VM. 
This event is issued with GC disabled. GC is re-enabled after Not ifvE vent returns. 

struct { 

char *begin; 

char *end; 

jint num_traces; 

JVMPI_CallTrace * traces; 

j int * threads^ status ; 
} monitor_dump; 

Contents: 

begin - start of the monitor dump buffer* 

end - end of the dump buffer 

num_traces - number of thread traces* 
traces - traces of all threads. 

thread^jStatus - status of all threads. 

The format of the monitor dump buffer is described in detail in the JVMPI Dump Formats 
section. 
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JVHP I_£VEKT_MOKI TOR_WAI T 

Sent when a thread is about to wait on an object. 

This event is issued with GC disabled. GC is re-enabled after Not if vEvent returns. 

struct { 

iobiectID object; 

jlong timeout; 
} monitor_wait ; 

Contents: 

obj ect - ID of object on which the current thread is going to wait. 

(NOLL indicates the thread is in Thread, sleep*) 

- the number of milliseconds the thread will wait (0 indicates waiting 
timeout foreven) 

JVMPI_EVENT_MDNI TOR__WAlTED 

Sent when a thread finishes waiting on an object. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 

struct { 

iobiectID object; 

jlong timeout; 
} monitor_wait; 

Contents: 

ob j ect - ID of object on which the current thread waited. 

(null indicates the thread is in Thread, sleep.) 
timeout - the number of milliseconds the thread waited. 

JVMP I_EVEOT_OB JECT_ALLOC 

Sent when an object is allocated, or when the profiler agent requests a 
jvmfi_event_OBJ£CT_alloc event by issuing a RequestEvent call. In the latter case, the 
jvmfi_REQUESTED_event bit in the event type is set. 

This event is issued with GC disabled. GC is re-enabled after NotifyEvent returns. 



struct { 

jint arena_id; 

i obi ect ID classed; 

jint is_ array; 

jint size; 

iobiectID obj_id; 
} obj _a Hoc; 



Contents: 
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arena_id - arena where allocated. 

. - class to which this object belongs, or the array element class if 
class_id .^ array j S jvmpI_CLASS. 

is_array - values can be: 

jvmpi normaljobject normal object 



JVMPI_ 


_C1ASS 


array of objects 


JVMPI_ 


^BOOLEAN 


array of booieans 


JVMPI_ 


_BYTE 


array of bytes 


JVMPI_ 


_CHAR 


array of chars 


JVMPI, 


_SHORT 


array of shorts 


JVMPI_ 


_INT 


array of ints 




^LONG 


array of longs 


JVMPI_ 


_FLOAT 


array of floats 


JVNPI_ 


^DOUBLE 


array of doubles 



size - size in number of bytes, 
objid - unique object ID. 

JVMP I_£VENT__OB JE CTJDUMP 

Sent when requested by the RgguestBvenn function. The iobiectID of the object for which a 
dump is being requested should be passed as the second argument to RequestEvent. 

The profiler agent should request this event with GC disabled. 

The event-specific data contains a snapshot of the object. 

struct { 

jint data^len; 

char *datla; 
} object^_durap; 

Contents: 

data_len - length of the object dump buffer 
data - beginning of the object dump 

The format of the object dump buffer is described in detail in the JVMPI Dump Formats 
section. 

JVHPX_EVENT_OBJECT_FREE 

Sent when an object is freed. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via malloc). 



This event is always sent between a pair of jvmpi event gc start and 

jvmpi event gc FINISH events. The profiler agent should acquire all the locks need for 
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processing this event in the event handler for jvmpi J£Vent_gc_start. 

struct { 

johnectlD obj__id; 
} obj_free; 

Contents: 

ob j_id - object being freed. 

JVMP I_EVENT J3B JBCT_MOVE 

Sent when an object is moved in the heap. 

This event is issued in the thread suspended mode. The profiler must not make any blocking 
calls such as entering a monitor or allocating from the C heap (for example, via malloe). 

This event is always sent between a pair of jvmpi event gc start and 

jvmfi event gc FINISH events. The profiler agent should acquire all the locks need for 

processing this event in the event handler for jvmpi_event jsc_start. 

struct { 

jint arena__id; 
jobiectlD obj__id; 
jint new_arena__id; 
job-iectID new_obj_id; 
) obj_move; 

Contents: 

arena_id - current arena. 
obj_id - current object ID. 

new__arena_id - new arena. 
new_obj_id - new object ID. 

JVMP X_EV£NT fc R7W_MDNXTOR^CONTENDED_EN!TER 

Sent when a thread is attempting to enter a raw monitor already acquired by another thread. 

struct { 

char *name; 

JVM PI RawMonitor id; 
} ra w jtnonit or; 

Contents: 

name - name of the raw monitor 
id - ID of the raw monitor 

JVMPI_EVENT_RAW_MONITOR_CONTENDED_ENTERED 

Sent when a thread enters a raw monitor after waiting for it to be released by another thread. 
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struct { 

char *name; 

JVMPI_RawMonitor id; 
} raw__itionitor; 

Contents: 

name - name of the raw monitor 
id - ID of the raw monitor 



Sent when a thread exits a raw monitor, and another thread is waiting to acquire the same 
monitor. 

struct { 

char *name; 

JVMPI_RawMonitor id; 
> raw_monitor; 

Contents: 

name - name of the raw monitor 
id - ID of the raw monitor 



JVWPI__EVENT_TKREAD_£ND 

Sent when a thtead ends in the VM. 

The env_id field of the jvMPi_Event received in this event notification is the JNiEnv interface 
pointer of the thread that ended- 

JVMPI__EVENT_THREAD_START 

Sent when a thread is started in the VM* or when the profiler agent requests a 
OVMPI^EVENT JTHR£Ad_Start event by issuing a ReouegtEvgnt call. In the latter case, the 
jvmpi~requested_event bit in the event type is set 

This event is issued with GC disabled. GC is re-enabled after Not ifyE vent returns. 

struct { 

char *thread_name; 

char *group_name; 

char *parent_name ; 

i object IP thread__id; 

JNIEnv *thread__env_id; 
} thread start; 



Contents: 
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threadjname - name of thread being started. 
group_name - group to which the thread belongs. 
parent_name - name of parent 
threaded - thread object ID. 
thread_env_id - JNIEnv * of the thread. 

Threads are associated with a JNIEnv pointer and a thread object ID. The JVMPI uses the 
jkiehv pointer as the thread ID. 

4. Dump Formats 

4,1 Sizes and Types Used in Dump Format Descriptions 

ul : 1 byte 
u2 : 2 bytes 
u4 ; 4 bytes 
us : 8 bytes 
ty: ul where: 



JVMPI_ 


jNORMAL_OBJECT 


normal object 


JVMPI^ 


_CLASS 


array of objects 


JVMPI_ 


BOOLEAN 


array of booleans 


JVMPI_ 


BYTE 


array of bytes 


JVMPI_ 


_CHAR 


array of chars 


JVMPI^ 


_SHORT 


array of shorts 




_INT 


array of ints 


JVMPI_ 


JLONG 


array of longs 


JVWPI_ 




array of floats 


JVMPI^ 


^DOUBLE 


array of doubles 



vi ; values, exact size depends on the type of value: 

boolean, byte ul 

short, char u2 

int, float u4 

long, double u8 

JNIEnv *, j object ID, and OVMPI_RawMoni tor sizeof(void *) 



4.2 Heap Dump Format 

The heap dump format depends on the level of information requested. 

JVMPI_PUKP_I£VEIi 0: 

The dump consists of a sequence of records of the following format: 
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ty type of object 

j object ID Object 

JVKP I_DUMPJu£VEL 1: 

The dump format islhc same as that of jvmpi_dump_level_2, except that the following values are 
excluded from the dump: primitive fields in object instance dumps, primitive static fields in class 
dumps, and primitive array elements. 

JVMPI_DUMP_LEVEIj 2: 

The dump consists 6F a sequence of records, where each record includes an 8-bit record type followed 
by data whose format is specific to each record type. 



Record type 


Record data 


JVM PI GC RQOT_UN KNOWN 

(unknown root) 


j object ID object 


JVM PI GC ROOT_ JN I_GLOBAL 

(JNI global ref root) 


j object ID object 

j ob j ect JNI global reference 


JVMPI GC ROOT JNI LOCAL 

(JNI local ref) 


j object ID object 
JNI En v * thread 

frame # in stack trace (-1 for 
u4 empty) 


JVMPI_GC_ROOT_JAVA_FRAME 

(Java stack frame) 


j object ID object 
JNIEnv * thread 

frame # in stack trace (-1 for 
u4 empty) 


JVMP I_GC_ROOT_NAT I VE_S TACK 

(native stack) 


j object ID object 
JNIEnv * thread 


JVMP I_GC_ROOT_S T I CKY_CLAS S 

(systenTclass) 


j ob j ectID class object 


JVMPI_GC_ROOT_THREAD_BLOCK 

(reference from thread block) 


j ob j ect I D thread object 
JNIEnv * thread 


JVMPI_GC_ROOT_MONITOR_USED 

"(entered monitor) " 


jobjectID object 


JVMPI_GC_CLASS_DUMP 

(dump of a class object) 


j object id class 
jobjectID super 
j ob j ectID class loader 
jobjectID signers 
j ob j ect I D protection domain 
void * reserved 
void * reserved 
u4 instance size (in bytes) 
[jobjectID]* interfaces 
u2 size of constant pool 
( u2 , constant pool index, 
ty, type, 
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vl) * 


value 1 
static field values 


JVMP I__GC_INS T ANCE_DOMP 

(dump of a normal object) 


jobjectID 
jobjectID 
u4 

tvl]* 


object 
class 

number of bytes that follow 
instance field values (class, 
followed by super, super's 
super ..,) 


JVMPl__GC_OBJ_ARRAY_DUMP 

(dump of an object array) 


jobjectID 
u4 

jobjectID 
[jobjectID] * 


array object 
number of elements 
element ciass hj ^may oe 
null in JDK L2) 
elements 


JVMPIJSC_PRIM_ARRAY_DUMP 

(dump of a primitive array) 


jobjectID 
u4 

ty 

tvl]* 


array object 
number of elements 
element type 
elements 



43 Object Dump Format 

The dump buffer consists of a single record which includes an 8-bit record type, followed by data 
specific to the record type. The record type can be one of the following: 

• JVMPI_GC_CLASS_DUMP 

• JVMPI_GC__INSTANC£_DUMP 

• JVMP I_GC_OB J_ARRA Y__DUM P 

• JVMPI_GC_PRIM_ARRAY_DUMP 

The format of the data for each record type is the same as described above in the heap dump format 
section. The level of information is the same as *jvmpi_dump_LEvel_2, with all of the following 
values included: primitive fields in object instance dumps, primitive static fields in class dumps, and 
primitive arrays elements. 

4.4 Monitor Dump Format 

The dump buffer consists of a sequence of records, where each record includes an 8-bit record type 
followed by data whose format is specific to each record type. 



Record type 


Record data 


JVMP I _MON I TOR_ JAVA 

(Java monitor) 


jobjectID 
JNIEnv * 
u4 
u4 

(JNIEnv *] * 
u4 

(JNIEnv *]* 


object ID 
owner thread 
entry count 

number of threads waiting to enter 

threads waiting to enter 

number of threads waiting to be 
notified 

threads waiting to be notified 
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~ 


char * 


raw monitor name 




JVMPI JfcawMoni tor 


raw monitor ID 




JNIEn^ * 


owner thread- 


JVMPI MONITOR_RAW 

(Raw monitor) 


u4 


entry count 


u4 

[JNIEnv + J + 


number of threads waiting to enter 
threads waiting to enter 




u4 


number of threads waiting to be 




notified 




[JNIEnv 


threads waiting to be notified 



5. Data Types 

Characters are encoded using the UTF-8 encoding as documented in the Java virtual machine 
specification- 
job jectXD 

An opaque pointer representing an object ID. 
struct _jobjectXD; 

typedef struct _ jobjectID * jobjectlD; 
JVMPljCallFrasae 

A method being executed. 

typedef struct { 

jint lineno; 

jmethodID method_id; 
} JVMPI_CallFrame; 

Fields: 

line number - line number in the source file, 
me thod_i d - method being executed. 

JVHP X_Cal 1£ race 

A call trace of method execution. 



typedef struct { 

JNIEnv *env_id; 

jint num_f rames ; 

JVMPI Call Frame * frames; 
) JVMPI CallTrace; 



Fields: 
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cnv_id - ED of thread which executed this trace. 

num_frames - number of frames in the trace. 

-the jvmpi CallPrame S that make up this trace. Callee followed by 
frames calIe ^ 



JVME>I_Field 

A field defined in a class. 



typedef struct { 

char * f ield_naiue ; 

char *field_signature; 
} JVMPI_Field; " 

Fields: 

f ieid^name - name of field 

f ield_signature - signature of field 
JVMPI_He apDTnapAr g 

Additional info for requesting heap dumps. 

typedef struct { 

jint heap_dump_ level ; 
} JVMPI__HeapDumpArg; 

Fields: 

heap^dump^level - level of heap dump information, values can be: 

JVMPI_DUMP_LEVEL_0 
JVMPIJDUMP_LEVEL_1 
JVMPI_DUMP_LEVEL_2 

*TVMP X_Xiineno 

A mapping between source line number and offset from the beginning of a compiled method. 

typedef struct { 

jint offset; 

jint lineno; 
} JVMPI_Lineno; 

Fields: 



offset - offset from beginning of method 
lineno - lineno from beginning of source file 



JVMPI Method 
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A method defined in a class. 

typedef struct { 

char *method_nan\e; 

char *xnethod_signature; 

jint start_lTneno; 

jint end_lineno; 

jmethodID fftethod_id; 
} JVMPI_Method; 

Fields: 

roethod__name 
method_signature 
start_lineno 
end_ lineno 
method^id 

JVMI>I_RawMonifcor 

An opaque pointer representing a raw monitor. 

struct _JVMPI_RawMonitor; 

typedef struct _JVMPI_RawMonitor * JVMPI_RawMonitor ; 

6. Notes on JDK1.2 Implementation Limitations 

• jvmpi_£V£NT_ob ject_alloc events for object arrays are issued with unknown element class 
IDs (i.e M the classed field is always null). 

• On Win32 the following events are not yet supported in the presence of the JIT compiler: 

JVMPIJEVENT_METHOD_ENTRY, 
JVMPI_EV£NT_METHOD_ENTRY2 , 
JVMP I_EVENT_METHOD~EX I T, 
JVMPI_EVENT^COMPIL£D_METHOD_LOAD t and 

jvmpi"event*compiled_method_onload» 

• SuspendThread must be called with the GC is disabled- GC must remain disabled until all 
threads have been resumed, 

• The thread start event for the main thread (first thread the VM creates) may arrive after some 
other events that refer to its JNIEnv interface pointer, 

• jvm p i _e ven t_aren a_n ew and jtvmpi_event_arena_DELete events are never issued. Arena 
IDs in other events are always set to L 



- name of method 

- signature of method 

- start line number in the source file 

- end line number in the source file 

- ID given to this method 



Last modified: Wed Nov 11 14:14:44 PST 1998 
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is claimed is: 

A method for allowing a profiler to communicate with a virtual machine without 
regard to a specific implementation of the virtual machine, the method comprising 
the steps of: 

creating one or more heap arenas in a heap; and 

using at least one event to dynamically manage storage allocation and storage 

deallocation in the heap, wherein said at least one event is independent of 
any algorithm for dynamically managing storage allocation and storage 
deallocation in the heap. 

The method of Claim 1, wherein the one or more heap arenas represent one or 
more logically partitioned portions in the heap. 

The method of Claim 1, further comprising assigning a unique arena ID to each 
heap arena. 

The method of Claim 1, further comprising at least one step of the following steps: 

using a new arena event when a new heap arena is created; 

using a delete_arena event with respect to a particular heap arena when all objects 

within a logically partitioned portion of the heap represented by the 

particular heap arena have been deleted; 
using one or more new_pbject events when one or more new objects are allocated 

in the new heap arena; 
using one or more delete_object events when one or more dead objects are returned 

to a free pool in the heap; and 
using one or more move_object events when one or more objects are moved from 

one heap arena to another heap arena. 

The method of Claim 4, further comprising associating each object with a unique 
arena ID, a unique object ID, and a unique class ID. 

The method of Claim 1, further comprising: 
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initiating a new_arena event to create a new heap arena to represent a logically 

partitioned portion of the heap; 
initiating one or more new_object events when one or more new objects are 

allocated in the new heap arena ; and 
5 initiating one or more delete_object events when one or more dead objects are 

returned to a free pool in the heap. 

7. The method of Claim 1, further comprising: 

initiating a new_arena event to create a new heap arena to represent a logically 
partitioned portion of the heap; 
10 initiating one or more new_object events when one or more new objects are 

allocated in the new heap arena; 
initiating one or more moveobject events when the heap is compacted; and 
initiating one or more delete_object events when one or more dead objects are 
returned to a free pool in the heap. 

The method of Claim 1, further comprising: 

initiating two new_arena events to create a first and second heap arena to represent 
a corresponding first and second logically partitioned portions in the heap; 
initiating one or more new_object events when one or more new objects are 

allocated in the first heap arena; 
initiating one or more move__object events when one or more live objects are 

moved from the first heap arena to the second heap arena; and 
initiating a deletearena event with respect to the first heap arena when all objects 
within the first logically partitioned portion of the heap represented by the 
first heap arena have been deleted. 

The method of Claim 1, further comprising: 

initiating two or more new arena events to create a plurality of heap arenas to 

represent a corresponding plurality of logically partitioned portions in the 
heap; 

initiating one or more new_object events when one or more new objects are 

allocated in a youngest heap arena corresponding to a youngest logically 
partitioned portion of the heap; 



15 8. 
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initiating one or more move_object events when one or more objects are moved 
from a younger heap arena to an older heap arena; and 

initiating a delete_arena event with respect to the youngest heap arena when all the 
objects within the youngest logically partitioned portion of the heap 
represented by the youngest heap arena have been deleted. 

A method for interfacing a profiler to a virtual machine, the method comprising the 
steps of: 

receiving from a profiler agent of the profiler at least one of either a request for 

specific types of events and information or an enablement of notification of 
specific types of events and information; and 

registering the specific types of events and information in which the profiler is 
interested. 

A computer-readable medium carrying one or more sequences of one or more 
instructions for allowing a profiler to communicate with a virtual machine without 
regard to a specific implementation of the virtual machine, the one or more 
sequences of one or more instructions including instructions which, when executed 
by one or more processors, cause the one or more processors to perform the steps 
of: 

creating one or more heap arenas in a heap; and 

using at least one event to dynamically manage storage allocation and storage 

deallocation in the heap, wherein said at least one event is independent of 
any algorithm for dynamically managing storage allocation and storage 
deallocation in the heap. 

The computer-readable medium of Claim 1 1, wherein the one or more heap arenas 
represent one or more logically partitioned portions in the heap. 

The computer-readable medium of Claim 1 1, further comprising assigning a 
unique arena ID to each heap arena. 

The computer-readable medium of Claim 11, further comprising at least one step 
of the following steps: 

using a new_arena event when a new heap arena is created; 
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using a delete_arena event with respect to a particular heap arena when all objects 

within a logically partitioned portion of the heap represented by the 

particular heap arena have been deleted; 
using one or more new_object events when one or more new objects are allocated 

in the new heap arena; 
using one or more delete_object events when one or more dead objects are returned 

to a free pool in the heap; and 
using one or more move_object events when one or more objects are moved from 

one heap arena to another heap arena. 

The computer-readable medium of Claim 14, further comprising associating each 
object with a unique arena ID, a unique object ED, and a unique class ID. 

The computer-readable medium of Claim 11, further comprising: 

initiating a new_arena event to create a new heap arena to represent a logically 

partitioned portion of the heap; 
initiating one or more new_object events when one or more new objects are 

allocated in the new heap arena ; and 
initiating one or more delete_pbject events when one or more dead objects are 

returned to a free pool in the heap. 

The computer-readable medium of Claim 11, further comprising: 

initiating a new_arena event to create a new heap arena to represent a logically 

partitioned portion of the heap; 
initiating one or more new_object events when one or more new objects are 

allocated in the new heap arena; 
initiating one or more move_object events when the heap is compacted; and 
initiating one or more delete_object events when one or more dead objects are 

returned to a free pool in the heap. 

The computer-readable medium of Claim 11, further comprising: 

initiating two new_arena events to create a first and second heap arena to represent 

a corresponding first and second logically partitioned portions in the heap; 
initiating one or more new_object events when one or more new objects are 

allocated in the first heap arena; 
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initiating one or more move_object events when one or more live objects are 
moved from the first heap arena to the second heap arena; and 

initiating a delete arena event with respect to the first heap arena when all objects 
within the first logically partitioned portion of the heap represented by the 
first heap arena have been deleted. 

The computer-readable medium of Claim 11, further comprising: 

initiating two or more new_arena events to create a plurality of heap arenas to 

represent a corresponding plurality of logically partitioned portions in the 

heap; 

initiating one or more new__object events when one or more new objects are 

allocated in a youngest heap arena corresponding to a youngest logically 
partitioned portion of the heap; 

initiating one or more move_object events when one or more objects are moved 
from a younger heap arena to an older heap arena; and 

initiating a delete_arena event with respect to the youngest heap arena when all the 
objects within the youngest logically partitioned portion of the heap 
represented by the youngest heap arena have been deleted. 

A computer-readable medium carrying one or more sequences of one or more 
instructions for interfacing a profiler to a virtual machine, the one or more 
sequences of one or more instructions including instructions which, when executed 
by one or more processors, cause the one or more processors to perform the steps 
of: 

receiving from a profiler agent of the profiler at least one of either a request for 

specific types of events and information or an enablement of notification of 
specific types of events and information; and 

registering the specific types of events and information in which the profiler is 
interested. 

A system for profiling a heap, the system comprising: 
a memory; 

one or more processors coupled to the memory; and 
at least one processor configured to: 
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create one or more heap arenas in a heap; and 

use at least one event to dynamically manage storage allocation and storage 
deallocation in the heap, wherein said at least one event is 
independent of any algorithm for dynamically managing storage 
5 allocation and storage deallocation in the heap. 

22. The system of Claim 21, wherein the one or more heap arenas represent one or 
more logically partitioned portions in the heap. 

23. The system of Claim 21, further comprising assigning a unique arena ID to each 
heap arena. 

10 24. The system of Claim 21, further comprising at least one step of the following steps: 
using a new_arena event when a new heap arena is created; 
using a delete_arena event with respect to a particular heap arena when all objects 
within a logically partitioned portion of the heap represented by the 
particular heap arena have been deleted; 
15 using one or more new__object events when one or more new objects are allocated 

in the new heap arena; 
using one or more delete_object events when one or more dead objects are returned 

to a free pool in the heap; and 
using one or more move object events when one or more objects are moved from 
20 one heap arena to another heap arena. 

25. The system of Claim 24, further comprising associating each object with a unique 
arena ID, a unique object ID, and a unique class ID. 

26. The system of Claim 21, further comprising: 

initiating a new arena event to create a new heap arena to represent a logically 
25 partitioned portion of the heap; 

initiating one or more new object events when one or more new objects are 

allocated in the new heap arena ; and 
initiating one or more delete_object events when one or more dead objects are 

returned to a free pool in the heap. 
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The system of Claim 21, further comprising: 

initiating a new_arena event to create a new heap arena to represent a logically 

partitioned portion of the heap; 
initiating one or more new_object events when one or more new objects are 

allocated in the new heap arena; 
initiating one or more move_object events when the heap is compacted; and 
initiating one or more delete_object events when one or more dead objects are 

returned to a free pool in the heap. 

The system of Claim 21, further comprising: 

initiating two new_arena events to create a first and second heap arena to represent 

a corresponding first and second logically partitioned portions in the heap; 
initiating one or more new_object events when one or more new objects are 

allocated in the first heap arena; 
initiating one or more move_object events when one or more live objects are 

moved from the first heap arena to the second heap arena; and 
initiating a delete__arena event with respect to the first heap arena when all objects 

within the first logically partitioned portion of the heap represented by the 

first heap arena have been deleted. 

The system of Claim 21, further comprising: 

initiating two or more new_arena events to create a plurality of heap arenas to 

represent a corresponding plurality of logically partitioned portions in the 
heap; 

initiating one or more new_object events when one or more new objects are 

allocated in a youngest heap arena corresponding to a youngest logically 
partitioned portion of the heap; 

initiating one or more move_object events when one or more objects are moved 
from a younger heap arena to an older heap arena; and 

initiating a delete_arena event with respect to the youngest heap arena when all the 
objects within the youngest logically partitioned portion of the heap 
represented by the youngest heap arena have been deleted. 

A system for profiling a heap, the system comprising: 
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a memory; 

one or more processors coupled to the memory; and 
at least one processor configured to: 

receive from a profiler agent of a profiler at least one of either a request for 
5 specific types of events and information or an enablement of 

notification of specific types of events and information; and 
register the specific types of events and information in which the profiler is 
interested. 

31. A system for profiling a heap, the system comprising: 
10 a storage medium; and 

a profiler front-end, wherein the profiler front-end is communicatively coupled to a 

profiler agent and is on a machine process separate and distinct from the 

machine process of the profiler agent; and 
a profiler agent communicatively coupled to the storage medium, wherein the 
15 profiler agent is configured to submit at least one of either a request for 

specific types of events and information or an enablement of notification of 

specific types of events and information. 

32. A virtual machine comprising a process for creating a plurality of arenas within a 
heap. 

20 33. A virtual machine having a standard profiler interface accommodating two or more 
profilers. 

34. The virtual machine of Claim 33, wherein one of said two or more profilers reports 
on activities of a Mark-and-Sweep garbage collector. 

35. The virtual machine of Claim 33, wherein one of said two or more profilers reports 
25 on activities of a Mark-Sweep-Compact garbage collector. 

36. The virtual machine of Claim 33, wherein one of said two or more profilers reports 
on activities of a Two-Space-Copying garbage collector. 

37. The virtual machine of Claim 33, wherein one of said two or more profilers reports 
on activities of a Generational garbage collector. 
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38. The virtual machine of Claim 33, wherein one of said two or more profilers reports 
on activities of a Reference-Counting garbage collector. 
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ABSTRACT OF THE DISCLOSURE 

A method and apparatus for profiling a heap. According to the method, a flexible 
and comprehensive general-purpose profiling interface that uniformly accommodates a 
wide variety of memory allocation and garbage collection methods is used. The profiling 
interface, among other things, employs a set of virtual machine profiling interface events 
that support all known types of garbage collection methods. 
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